Neurocaps

- Entails some code cleaning and verification to ensure that the code cleaned for clarity purposes produces the same
results.

🚀 New/Added
- Davies Bouldin and Variance Ratio (Calinski Harabasz) added

♻ Changed
- For `CAPs.calculate_metrics()` if performing an analysis on groups where each group has a different number of CAPs, then for "temporal_fraction",
"persistence", and "counts", "nan" values will be seen for CAP numbers that exceed the group's number of CAPs.
- For instance, if group "A" has 2 CAPs but group "B" has 4 CAPs, the DataFrame will contain columns for CAP-1,
CAP-2, CAP-3, and CAP-4. However, for all members in group "A", CAP-3 and CAP-4 will contain "nan" values to
indicate that these CAPs are not applicable to the group. This differentiation helps distinguish between CAPs
that are not applicable to the group and CAPs that are applicable but had zero instances for a specific member.

🐛 Fixes
- Adds error earlier when tr is not specified or able to be retrieved form the bold metadata when the condition is specified
instead of allowing the pipeline to produce this error later.
- Fixed issue with `show_figs` in `CAP.caps2surf()` showing figure when set to False.

♻ Changed
- With parallel processing, joblib outputs are now returned as a generator as opposed to the default, which is a list,
to reduce memory usage.

♻ Changed
- Changed how ids are organized in respective group when initializing the `CAP` class. In version 0.11.1, the ids are
sorted lexicographically:
python3
self._groups[group] = sorted(list(set(self._groups[group])))

This doesn't affect functionality but it may be better to respect the original user ordering.This is no longer the case.

🐛 Fixes
- Fix for python 3.12 when using `CAP.caps2surf`.
- Changes in pathlib.py in Python 3.12 results in an error message format change. The error message now includes
quotes (e.g., "not 'Nifti1Image'") instead of the previous format without quotes ("not Nifti1Image"). This issue
arises when using ``neuromaps.transforms.mni_to_fslr`` within CAP.caps2surf() as neuromaps captures the error as a
string and checks if "not Nifti1Image" is in the string to determine if the input is a NifTI image. As a patch,
if the error occurs, a temporary .nii.gz file is created, the statistical image is saved to this file, and it is
used as input for neuromaps.transforms.mni_to_fslr. The temporary file is deleted after use. Below is the code
implementing this fix.

python3
Fix for python 3.12, saving stat map so that it is path instead of a NifTi
try:
gii_lh, gii_rh = mni152_to_fslr(stat_map, method=method, fslr_density=fslr_density)
except TypeError:
Create temp
temp_nifti = tempfile.NamedTemporaryFile(delete=False, suffix=".nii.gz")
warnings.warn(
textwrap.dedent(
f"""
Potential error due to changes in pathlib.py in Python 3.12 causing the error
message to output as "not 'Nifti1Image'" instead of "not Nifti1Image", which
neuromaps uses to determine if the input is a Nifti1Image object.
Converting stat_map into a temporary nii.gz file (which will be automatically
deleted afterwards) at {temp_nifti.name}
"""
)
)
Ensure file is closed
temp_nifti.close()
Save temporary nifti to temp file
nib.save(stat_map, temp_nifti.name)
gii_lh, gii_rh = mni152_to_fslr(temp_nifti.name, method=method, fslr_density=fslr_density)
Delete
os.unlink(temp_nifti.name)

- Final patch is for strings in triple quotes. The standard textwrap module is used to remove the indentations at each
new line.

💻 Metadata
- Very minor explanation added to `CAP.calculate_metrics` regarding using individual dictionaries from merged
dictionaries as inputs.

💻 Metadata
- Two docstring changes for `merge_dicts`, which includes nesting the return type hint and capitalizing all letters of
the docstring header for aesthetics.