introduce map.get_volume() which returns a FilteredVolume

[AhmetNSimsek]

Based on #554 (comment)

• Remove region_or_index in map.fetch(). New use:

map.fetch('region name') or map.fetch(region='region name')
map.fetch(index=<MapIndex>)

• fixes region.get_regional_map only returns the mask of the maps #602. region.get_regional_map only gets a volume that is mapped in a parcellation map. region.get_regional_mask gets a volume to use as a mask, and also can combine several child masks to create a mask for parent regions. threshold only applies to get_regional_mask and for statistical maps.
• Introduce map.get_volume which returns a FilteredVolume. FilteredVolume can have label, fragment, and threshold specifications to allow for lazy fetching of these specifications and these only. get_regional_mask always return a FilteredVolume. get_regional_map can return a Volume if the map is defined as an individual volume in the configuration; but they do not have more information like a labelled map volume of julich brain 2.9 on mni152 space.
• remove via_space kwarg from region.get_regional_map. This was performing a linear transformation and it is not explicit. Deprecated for clarity as users can resample the maps themselves with nilearn if they'd like.

[AhmetNSimsek]

Dev Meeting 2024-12-06: The PR is a go. Just need to update the tests.

[codecov]

Codecov Report

Attention: Patch coverage is 42.24138% with 67 lines in your changes missing coverage. Please review.

Project coverage is 45.60%. Comparing base (e45a688) to head (667ac1d).
Report is 27 commits behind head on main.

Files with missing lines	Patch %	Lines
siibra/volumes/volume.py	44.44%	25 Missing ⚠️
siibra/core/region.py	47.22%	19 Missing ⚠️
siibra/volumes/parcellationmap.py	46.66%	8 Missing ⚠️
siibra/volumes/providers/neuroglancer.py	20.00%	8 Missing ⚠️
siibra/locations/boundingbox.py	28.57%	5 Missing ⚠️
siibra/volumes/providers/nifti.py	33.33%	2 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #624      +/-   ##
==========================================
- Coverage   46.14%   45.60%   -0.54%     
==========================================
  Files          75       75              
  Lines        7171     7194      +23     
==========================================
- Hits         3309     3281      -28     
- Misses       3862     3913      +51     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.