Add all Kim's DevCCFv1 atlases

[carlocastoldi]

Description

With this draft PR i ask you your opinion and help to first:

• allow the script to download the resources from the official OneDrive page
• have a general review of the script's code quality before adapting it to generate the other combination of atlases/references
• choose which atlases are worth generating and whether they should update any previous atlas

Lastly, I have tested this script on two setups: on one computer without parallelization and the other with. The run with parallelization didn't manage the memory properly and run OOM on linux, effectively making the generation of the atlas much slower. Does BrainGlobe offer any help in the management of the parallelization or should I do it myself?

P.S. if needed, I can provide the resulting atlas from this script

What is this PR

• Bug fix
• Addition of a new feature
• Other

Why is this PR needed?
To perfection the support to Kim's developing mouse brain atlases

What does this PR do?
It adds a script for generating Kim's DevCCFv1 mouse atlas. For now, it generates only the P14 altas with LSFM@20µm as reference, ignoring the other ages (E11.5, E13.5, E15.5, E18.5, P4 and P56) and references (they are all MRI@50 µm)

References

#425

How has this PR been tested?

The resulting atlas from the script was used within ABBA

Is this a breaking change?

No.

Does this PR require an update to the documentation?

It does, but it is not included yet in this PR

Checklist:

• The code has been tested locally
• Tests have been added to cover all new functionality (unit & integration)
• The documentation has been updated to reflect any changes
• The code has been formatted with pre-commit

[alessandrofelder]

Hey @carlocastoldi

Thanks a lot!

Does BrainGlobe offer any help in the management of the parallelization or should I do it myself?

We are aware that past parallelisation efforts are not robust #428, so if you would like to contribute a better way, even in just for one atlas, that might help us address #429 - so that would be great

choose which atlases are worth generating and whether they should update any previous atlas

I am happy to give my thoughts on code quality and how to download from OneDrive but can I first check (Pardon my naivety!): what is the difference here to the existing Kim Developmental atlas that is already packaged? Could this be an extension of that existing script?

[adamltyson]

what is the difference here to the existing Kim Developmental atlas that is already packaged? Could this be an extension of that existing script?

I think that is an earlier version of the P56 atlas.

@carlocastoldi ideally we would add all these atlases, but the number of ages x reference images is very large. In principle though, there's no reason why we can't add them all. Each would have to be a seperate atlas (at least until we built Atlas API V2). Would you be willing to write a script that can add all of these atlases?

[carlocastoldi]

We are aware that past parallelisation efforts are not robust #428, so if you would like to contribute a better way, even in just for one atlas, that might help us address #429 - so that would be great

Oh okay, i see that! It's something I may perhaps look into, but for now it can't be my priority...

can I first check (Pardon my naivety!): what is the difference here to the existing Kim Developmental atlas that is already packaged? Could this be an extension of that existing script?

Oh I tried to understand if the existing "developmental" atlas (it's not really developmental because it's only for P56, when mice are already adult. It's the same age at which Allen developed CCFv3) had any publication associated with it, but as far as i understood, that's only a v0.0.1 of the work they have recently published (v1). I am not 100% sure about it, tho, as i can't find any description/publication about that dataset.
Surely, however, it is not compatible with their v1 as they differ in resolution, coordinate system, ontology and reference.
Rather, these atlases are closer to those of ADMBA, however they would also make them outdated (ADMBA's are very low resolution and hard to work with due to their undefined region boundaries).

Lastly they offer two different resolutions: one at 20µm for LSFM references and one at 31.5µm/40µm/50µm (depending on the age of the atlas) for MRI references and some stereotaxic coordinates (for post-natal atlases).
For now, in this PR, i would focus on adding just LFSM@20µm atlases.

I am happy to give my thoughts on code quality and how to download from OneDrive

Thank you a lot!

[adamltyson]

For now, in this PR, i would focus on adding just LFSM@20µm atlases.

That seems sensible, thanks!

[carlocastoldi]

@carlocastoldi Would you be willing to write a script that can add all of these atlases?

Oh i missed this message, sorry!
But yes, sure. I'm down for it. However at the moment the script assumes that the resources are already downloaded and it does not retrieve them from official channels as they are on OneDrive

[carlocastoldi]

only one question remains: would you be okay if this PR also deleted the scripts for generating ADMBA and old KimP56 atlases?

They are all superseded by this new version for the developing mouse. Leaving them all would otherwise overcrowd the list of supported atlases

[adamltyson]

For now, I think we should keep them. Although the new atlases may be better, there are still researchers using the old ones for ongoing projects.

We also want to ensure that BrainGlobe acts as an archive in case the original files cannot be found for older atlases.

Longer term, we will find a solution for making the set of available atlases easier to navigate (e.g. atlas groups).

[carlocastoldi]

Sure
Thank you for the explanation!

[alessandrofelder]

Thanks again for this, @carlocastoldi - and thank you and @adamltyson for your clarifications.

The code looks largely good on a first pass (I haven't run it, but it's promising you could use it in ABBA 🙌 ), made two small comments.

Do either of you know how official the OneDrive folder is? It looks like in the publication they point to this Figshare repo. Using this repo instead would make it easy to use pooch to download and cache them neatly (and it's likely a more robust place to get data from long-term)?

[carlocastoldi]

Do either of you know how official the OneDrive folder is?

Is the official download page from their website, apparently.

One that could get updated and be changed when new versions come out, I imagine.

[alessandrofelder]

Hmmm, I see.

I'd still prefer going with the figshare data if possible, because

• it has a license
• it is versioned by a DOI
• it is linked to from the publication we include in the metadata
• (it's easier to download programmatically... haven't found a way to easily generate a sensible download link from OneDrive)

I'm not sure how standardised new versions published on OneDrive would be?
Would they make a new folder somewhere? Would they overwrite some of the existing files?
I may be missing something.

What do you think @carlocastoldi ?

[carlocastoldi]

Sure, i see all the upsides of using figshare. I guess I was worried that we wouldn't notice any update to the published atlas unless we actively search for them, but that's a minor issue!

I'll work on this PR by using pooch on Figshare. Thank you all!

[carlocastoldi]

With this last commit, i think this PR is ready for review!

[adamltyson]

Thanks @carlocastoldi. The BrainGlobe team is checked out for the holidays now, so we'll take a look in the new year.

[carlocastoldi]

I figured!
I just wanted to have my part done before holidays. No hurry!

Happy holidays! ^^

[alessandrofelder]

Thanks a lot for this @carlocastoldi - I've tested the script locally on E11 and it's looking great 🎉 :

I can also confirm that the generated atlas (at least at E11) passes all our validation functions successfully.

I have a major comment that should be straightforward to handle (🤞 - happy to help)

The global variables seem to imply that the script handles all MODALITIES, but LSFM is hard-coded later on and we only loop over timepoints. We should document clearly on how the script is intended to be run.

Maybe for this PR, just LSFM is enough?

If we wanted the other modalities (in this PR or as a separate issue for now) Maybe easiest for use is to
- run LSFM by default
- have an argument to specify the modality on the command line: like python kim_devccf_mouse.py --modality MRI-dwi
- replace hard-coded LSFM with modality (and assert modality in MODALITIES)

This would allow running atlas generation in parallel for each modality on our HPC (as separate SLURM jobs)

I have also suggested removing any obsolete (AFAICT) commented-out code.

Let me know your thoughts :)

[alessandrofelder]

These are never used AFAICT - what is the intention for them? IIUC they are possible other modalities and resolutions that we don't loop over in the current version... maybe we want them in a later version?

[adamltyson]

Is there any reason why we can't just add them? We have all the modalities for the P56 atlas already.

[alessandrofelder]

Happy to add them, no reason why not - my question was more about what the intention of this PR is, because the current code puts the modalities into a list variable that is never used?

[adamltyson]

Sorry I meant - can we adapt this PR to include all modalities rather than just deleting this commented out list?

[carlocastoldi]

The existence of this list was intended as ~metadata of Kim's DevCCFv1 reference images, rather than for actual generation of the atlases.

The intent of this PR was to add LSFM only because:

• its the most accurate and at highest resolution (20um vs 50 um of MRI images)
• generating 7×6=42 atlases seemed too overwhelming for an user navigating the atlases through show_atlases() (et simil.) output. The atlases are 7, the only thing changing is the reference image. This, in my experience, creates a sort of "bias" and confusions.

That said I think i could do adapt the script to generate those atlases as well, if you confirm me you think it's appropriate! However, i would discourage from officially adding them to BrainGlobe, until #141 is not complete.

[adamltyson]

I think it's appropriate. Ideally we would wait until #141 is complete, but unfortunately, if we treat #141 as a blocker, there's a lot of things we won't get done!

[carlocastoldi]

as you wish. I modified the script to allow other modalities as well.

Now the last thing remaining is the naming convention of the atlases. What do you prefer?

1. kim_devccf_mouse_<MODALITY>_<AGE>
2. kim_devccf_mouse_<AGE>_<MODALITY>

The 2nd option is probably better for navigation

[carlocastoldi]

Thank you for the comments!

I still have some questions, tho. There are parameters I was a unsure of and for which i chose the default values, when generating the meshes. Could you please help me making and informed decision:

• closing_n_iters
• decimate_fraction
• smooth. The resulting meshes retain the voxels shape, as we can also see from @alessandrofelder screenshot. Should we smooth them out? How do you evaluate the quality of the meshes?

Also: is it correct to use these same parameters for every age (and sizes)?
Lastly: should I add the possibility to generate the atlases for MRI@50µm reference images, could I still use the annotation volume at 20µm instead?

Thank you in advance!

[alessandrofelder]

Could you please help me making and informed decision:

closing_n_iters
decimate_fraction
smooth. 

The resulting meshes retain the voxels shape, as we can also see from @alessandrofelder screenshot. > Should we smooth them out? How do you evaluate the quality of the meshes?

The meshes are meant for visualisation only, so I would suggest smoothing them with closing_n_iters=2 and smooth=True (which is the de facto default for most BrainGlobe atlases, I think).
The decimate fraction is useful if you want to reduce the size of the mesh files a bit (to improve download and rendering speeds) especially for larger, high-res atlas.
The quality "metric" is essentially: "Do the meshes look nice? (and are the mesh files not very big)?"

and

Also: is it correct to use these same parameters for every age (and sizes)?

Correct is probably not the right word, but it's up to us to decide whether one parameter is good enough (in our quality metric) for all ages. I suggest we try and adapt if needed.

[carlocastoldi]

The decimate fraction is useful if you want to reduce the size of the mesh files a bit (to improve download and rendering speeds) especially for larger, high-res atlas.

oh i understand! In light of this, do you reckon i should change the it based on the timepoint, since embryonic atlases are much smaller than post-natal?

Correct is probably not the right word, but it's up to us to decide whether one parameter is good enough (in our quality metric) for all ages. I suggest we try and adapt if needed.

would it be good if i exported it as an additioanl parameter of the script?

[alessandrofelder]

oh i understand! In light of this, do you reckon i should change the it based on the timepoint, since embryonic atlases are much smaller than post-natal?

Yea, potentially... I would experiment a bit. Also, does the resolution change at later timepoints or are all LSFM atlases 20 um?

[carlocastoldi]

Also, does the resolution change at later timepoints or are all LSFM atlases 20 um?

All LSFM atlases are at 20µm. At all embryonic and postnatal stages

[alessandrofelder]

Lastly: should I add the possibility to generate the atlases for MRI@50µm reference images, could I still use the annotation volume at 20µm instead?

What would be the advantage of doing so? Are you suggesting to resample the annotation volume at 20um to 50 um? It looks like there are 50um res annotation already available?

[carlocastoldi]

What would be the advantage of doing so? Are you suggesting to resample the annotation volume at 20um to 50 um? It looks like there are 50um res annotation already available?

I guess the advantage would be that we would retain the smaller structures that otherwise would not be visible at a lower resolution. I don't know if this is the case fore Kim's, but i am sure that 25µm Allen's does not display some small regions that instead are present int 10µm annotation volume

[alessandrofelder]

Thanks a lot for this @carlocastoldi!
It's looking really really good!

I will run the generation of at least the LSFM atlases tomorrow (need to focus on other things today - sorry!). I'll keep this PR open until the atlases are online, so I don't forget.

What would be great is if you could open an issue

• detailing the problems you encountered with the MRI and the ontology (I'm not sure I understand that entirely)
• and any other MRI related problems (different resolution of annotations? Too many atlases?)
  so we can tackle those separately to this PR (which already has a long discussion :D )

You are welcome to join our developer meeting later today (or another time) if you're free and would like to discuss the MRI side further - see the BrainGlobe zulip for details.

[carlocastoldi]

It's looking really really good!

Thank you a lot for the speed, accuracy and time you put into reviewing this!

I will run the generation of at least the LSFM atlases tomorrow (need to focus on other things today - sorry!). I'll keep this PR open until the atlases are online, so I don't forget.

No worries. I am not in hurry

You are welcome to join our developer meeting later today (or another time) if you're free and would like to discuss the MRI side further - see the BrainGlobe zulip for details.

sure! It would be a pleasure. I am new to zulip, is there an already-scheduled meeting i can register to? Or will we arrange privately? Found!
Thank you a lot!

What would be great is if you could open an issue

perhaps we can first discuss them in the meeting later today and evaluate if they are proper issues. If so, I will open the relative issues here, sure!

[carlocastoldi]

with the last commit i set the atlas naming to kim_devccf_mouse_<AGE>_<MODALITY>.

Last thing to discuss is whether this PR should include the change of the naming to overlap previous kim atlases in brainglobe (i.e. be it kim_dev_mouse_<AGE>_<MODALITY>).
If not, i think this script is ready to be merged, on my side!

[alessandrofelder]

Last thing to discuss is whether this PR should include the change of the naming to overlap previous kim atlases in brainglobe (i.e. be it kim_dev_mouse__).

I would be in favour of this last change, to make it clearer to BrainGlobe-only users that this is a newer version of the same atlas? @adamltyson may wish to chime in

[adamltyson]

Yeah, if no other reason than it's a slightly shorter name.

[carlocastoldi]

right.

Does that mean that I should set VERSION=3, since kim_dev_mouse is currently on version 2? And what about the old script? Should I delete it?

[adamltyson]

Does that mean that I should set VERSION=3, since kim_dev_mouse is currently on version 2?

I think so

And what about the old script? Should I delete it?

I think leave it for now, we don't (yet) have a process for this.

[carlocastoldi]

I found the issue I had when generating the meshes for embryonic mri atlases.

It was pooch having an unintuitive interface, in my opinion, extracting files from archives in a different order from the one you asked.
You might have seen it working on your OS cause it depends on how the filesystem lists files. Nonetheless it wouldn't have worked on a Linux system such as Slurm, i am afraid.

With this, i feel like this PR is finally concluded! 🎉