Atlas API documentation

[k1o0]

This PR mostly contains atlas documentation (changes to function docstrings). I wrote this section to help myself understand the library. It took me a long time to write this, everything was extremely opaque and the paper trail is scant.

I also refactored the following:

• atlas.atlas.FlatMap -> atlas.flatmaps.FlatMap
• atlas.flatmaps.plot_swanson_vector -> atlas.plots.plot_swanson_vector
• atlas.flatmaps.plot_swanson -> atlas.plots.plot_swanson
• atlas.flatmaps.annotate_swanson -> atlas.plots.annotate_swanson

This fixes all the circular import issues. There are branches in paper-brainwide-map, iblscripts, and ibldevtools that will need merging along side this.

There are still loads of holes in the documentation, here are a few big ones:

• No reference or explanation of Swansan flat map data.
• No explanation of the mappings. 'Beryl' and 'cosmos' appear to be arbitrary internal IBL mappings. Seems to be 0 info on Slack.
• No documentation of file fixtures. Some files clearly come from Allen and can be cited, others may have been generated in-house or manually extracted from publications?

Some of the citations need changing (according to @dbirman the Needles atlas does not use the Waxholm data). Once I've correct this I'll merge.

[dbirman]

Just to be clear I think I'm the one who is confused! I thought Needles = Dorr 2008 (not sure who told me this), but it sounds like it was made from the waxholm mouse paper. If that's right then I should update that in the Pinpoint docs as well

[k1o0]

@dbirman I clarified things with Nick, the correct citation for the needles atlas is indeed the Dorr 2008 paper (specifically it uses the DSURQE dataset). The Waxholm atlas doesn't appear to be used at all so I've removed that citation. Do you by chance know if we have the Allen CCF voxel location of lambda?

@oliche Having spoken to Nick and documented as much as I can, the rest is up to you. There's still a lot that needs explaining in the documentation, especially the flatmaps and plotting stuff. If we want this package to be used externally or for researchers to write their own methods sections we need this to be better documented.

[dbirman]

@dbirman I clarified things with Nick, the correct citation for the needles atlas is indeed the Dorr 2008 paper (specifically it uses the DSURQE dataset). The Waxholm atlas doesn't appear to be used at all so I've removed that citation. Do you by chance know if we have the Allen CCF voxel location of lambda?

Okay thanks for that clarification!

Lambda is a little tricky, because the location will depend on whether you are taking into account the pitch rotation that we know is present in the CCF. As implemented, the transforms in IBL do not apply the pitch, but it's more accurate to use it. If you use the pitch rotation, then Lambda is at (ap=9410, ml=5700, dv=-18.82088). Note that the DV coordinate is outside the CCF volume (because the CCF is pitched "down" relative to the true brain). If you don't apply the pitch, then you can just go straight back from bregma at the same level by approx. 4100 um, so bregma = (5400, 5700, 332) and lambda = (9500, 5700, 332)