[ENH] Allows users to get microarray samples in mask

[rmarkello]

Closes #46.

Adds function abagen.get_samples_in_mask(mask) which allows users to provide a mask (binary or otherwise 🤷‍♂️) and all samples within tolerance of mask boundaries are returned (along with MNI coordinates of samples). If no mask is provided, (i.e., mask=None) all available tissue samples are returned instead.

This required adding a region_agg=None option to abagen.get_expression_data(), though I am choosing not to document this functionality in favor of having people use get_samples_in_mask() directly so that the relevant sample coordinates are returned alongside expression data.

To do:

• Add smoke tests for get_samples_in_mask()
• Update documentation for function

[codecov]

Codecov Report

Merging #155 into master will increase coverage by 0.03%.
The diff coverage is 94.73%.

@@            Coverage Diff             @@
##           master     #155      +/-   ##
==========================================
+ Coverage   90.82%   90.85%   +0.03%     
==========================================
  Files          32       32              
  Lines        2201     2253      +52     
==========================================
+ Hits         1999     2047      +48     
- Misses        202      206       +4     

Impacted Files	Coverage Δ
abagen/allen.py	93.07% <93.47%> (-0.03%)	⬇️
abagen/__init__.py	100.00% <100.00%> (ø)
abagen/correct.py	98.60% <100.00%> (ø)
abagen/tests/test_allen.py	100.00% <100.00%> (ø)
abagen/samples_.py	99.21% <0.00%> (-0.79%)	⬇️

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 0cfe5f7...43f94a5. Read the comment docs.

[rmarkello]

Alright so the docs failure is a typo (shouldn't have done exp.head() but just exp) but it did highlight an issue with gene normalization when using get_samples_in_mask().

Namely, if a relatively small ROI is provided as the mask then often there are relatively few samples found within the mask for each donor. If normalization is set to 'srs' (the default), then 2/N samples will have expression values set to either 0 or 1 (due to the rescaling). While this is not normally an issue when aggregating over donors, when returning sample-level expression data these 0/1 values are retained and can make for very confusing interpretations (since the resulting expression matrix will have one 0 value for each donor and one 1 value for each donor. As such, normalization should probably be done over all available samples—not just those matched to the provided mask. However, this will requires modifying get_expression_data() in such a way that the functionality of that workflow does not change (since we generally want to retain the functionality there, I think—though now I might reconsider how that process should work...).