Non-intuitive defaults for `ano.label_points`

[ZachPenn]

Hi,

Really more of a suggestion. In the CellMap tutorial, when ano.label_points is called, the key = "order". This is also the underlying default in Annotation.py file. It took quite a while for me to track down that the label returned was not the label in the atlas, but the index from what I believe is an ordered dictionary, with no apparent link to the ABA nomenclature. I totally get there might be some reason under the hood for doing it like this, but it seems more intuitive as a user to have the following in the tutorial:

label = ano.label_points(coordinates_transformed, key='id');
names = ano.convert_label(label, key='id', value='name');

Because the user might want to map results back to ABA, having the default be the 'id' seems more natural, at least to me. If defaults or the tutorial aren't changed, perhaps the documentation could be a bit more informative on this issue.

Thanks so much!

Zach

[ywang219]

Hi Zach,

Thank you for the suggestion. I was able to get some results, but I am new to coding. Do you mean this annotation may not be as accurate compared to the brain atlas? Thank you!

[ZachPenn]

The default gives perfectly fine results. The issue is that the relationship to the Allen Brain Atlas is somewhat unclear. I expected that the default labeling would be the gray scale value in the Allen Brain Atlas or some other label contained within the aba annotation json file (e.g., 'id', 'graph_order', or 'name'). For example, to confirm that everything is working properly, I might check that a point centered within the ventral basolateral amygdala returns a value of 451, its ID in the Allen Brain Atlas. However, it returns something very different (it's 'order'). Because I don't have immediate access to the 'order' value for the basolateral amygdala or know how this was generated without looking in the backend code, 'order' is not particularly useful to me as a user.

[ywang219]

To clarify, you are saying the results are fine, meaning the regions are the same, but the ID can be different?

[ZachPenn]

Correct.

[ChristophKirst]

Hi, to clrify. The AB Atlas IDs contain some huge numbers for certain brain regions, which makes plotting or visualization hard (often only those regions show up in a not adjusted colormap etc). So we simply enumerate the brain regions as they appear in the JSON file an use these IDs to avoid those problems. There is a 1 to 1 correspondence between the order label and the ABA label so no information is lost etc.

I agree that this is sort of not intuitive and should be better documented. I will try to change that in the next update of ClearMap (or feel free to contribute).