Neurocaps

💻 Metadata
- Minor clarification in `CAP.caps2radar` function

♻ Changed
- Internal refactoring and minor change to saved filenames for some functions for consistency.

♻ Changed
- The `CAP.caps2radar` function now calculates the cosine similarity to the positive and negative activations of
a CAP cluster centroid separately. Each region has two traces (one for cosine similarity with positive activation
and one for cosine similarity with negative calculations). The plots should be easier to interpret and aligns better
with visualizations in CAP research.

🚀 New/Added
- In `CAP.caps2radar`, "round" (rounds to three decimal points by default) and "linewidth" kwargs added.
♻ Changed
- In `TimeseriesExtractor`, `parcel_approach` and `fwhm` have changed positions. `parcel_approach` is second in the
list and `fwhm` is seventh in the list.
- `flush_print` changed to `flush`.
- In `CAP.caps2radar`, both `method` and `alpha` removed. Only the traditional cosine similarity calculation is
computed.
- In `CAP.calculate_metrics`, calculation for counts changed to abide by the formula,
temporal fraction = (persistence * counts)/total volumes which can be found in the supplemental of
Yang et al., 2021](https://doi.org/10.1016/j.neuroimage.2021.118193). Counts is now the frequency of initiations
of a specific CAP.
💻 Metadata
- Version directives less than 0.16.0 removed.

- This update exclusively relates to improving documentation as well as improving the language in the error and
information messages for clarity. For instance, when a subject is skipped during timeseries extraction, instead of
`"[SUBJECT: 01 | SESSION: 002 | TASK: rest] Processing skipped: {message}"` it is now
`"[SUBJECT: 01 | SESSION: 002 | TASK: rest] Timeseries Extraction Skipped: {message}"`. Language in primarily in some
function descriptions have also been included.

♻ Changed
- All uses of `print` and `warnings.warn` in package replaced with `logging.info` and `logging.warning`. The internal
function that creates the logger:
python
import logging, sys


class _Flush(logging.StreamHandler):
def emit(self, record):
super().emit(record)
self.flush()


def _logger(name, level=logging.INFO, flush=False):
logger = logging.getLogger(name.split(".")[-1])
logger.setLevel(level)
Works to see if root has handler and propagate if it does
logger.propagate = logging.getLogger().hasHandlers()
Add or messages will repeat several times due to multiple handlers if same name used
if not logger.hasHandlers():
if flush:
handler = _Flush(sys.stdout)
else:
handler = logging.StreamHandler(sys.stdout)
handler.setFormatter(logging.Formatter("%(asctime)s [%(levelname)s] %(message)s"))
logger.addHandler(handler)

return logger

- **Note**: The logger is initialized within the [internal time series extraction function]((https://github.com/donishadsmith/neurocaps/blob/900bf7a89d3ff16a8dd91310c8d177c5b5d6de8a/neurocaps/_utils/_timeseriesextractor_internals/_extract_timeseries.py#L12)) to ensure that each child
process has its own independent logger. This guarantees that subject-level information and warnings will be properly
logged, regardless of whether parallel processing is used or not.

For non-parallel processing, the logger can be configured by a user with a command like the following:

python
logging.basicConfig(
level=logging.INFO,
format="%(asctime)s [%(levelname)s] %(message)s",
handlers=[logging.StreamHandler(sys.stdout), logging.FileHandler("info.out")],
)


- Subject-specific messages are now more compact.

**OLD:**

List of confound regressors that will be used during timeseries extraction if available in confound dataframe: Cosine*, Rot*.

BIDS Layout: ...0.4_ses001-022/ds000031_R1.0.4 | Subjects: 1 | Sessions: 1 | Runs: 1

[SUBJECT: 01 | SESSION: 002 | TASK: rest | RUN: 001]
----------------------------------------------------
Preparing for timeseries extraction using - [FILE: '/Users/runner/work/neurocaps/neurocaps/tests/ds000031_R1.0.4_ses001-022/ds000031_R1.0.4/derivatives/fmriprep_1.0.0/fmriprep/sub-01/ses-002/func/sub-01_ses-002_task-rest_run-001_space-MNI152NLin2009cAsym_desc-preproc_bold.nii.gz']

[SUBJECT: 01 | SESSION: 002 | TASK: rest | RUN: 001]
----------------------------------------------------
The following confounds will be for nuisance regression: Cosine00, Cosine01, Cosine02, Cosine03, Cosine04, Cosine05, Cosine06, RotX, RotY, RotZ, aCompCor02, aCompCor03, aCompCor04, aCompCor05.


**NEW:**

2024-09-16 00:17:11,689 [INFO] List of confound regressors that will be used during timeseries extraction if available in confound dataframe: Cosine*, aComp*, Rot*.
2024-09-16 00:17:12,113 [INFO] BIDS Layout: ...0.4_ses001-022/ds000031_R1.0.4 | Subjects: 1 | Sessions: 1 | Runs: 1
2024-09-16 00:17:13,914 [INFO] [SUBJECT: 01 | SESSION: 002 | TASK: rest | RUN: 001] Preparing for timeseries extraction using [FILE: sub-01_ses-002_task-rest_run-001_space-MNI152NLin2009cAsym_desc-preproc_bold.nii.gz].
2024-09-16 00:17:13,917 [INFO] [SUBJECT: 01 | SESSION: 002 | TASK: rest | RUN: 001] The following confounds will be for nuisance regression: Cosine00, Cosine01, Cosine02, Cosine03, Cosine04, Cosine05, Cosine06, aCompCor00, aCompCor01, aCompCor02, aCompCor03, aCompCor04, aCompCor05, RotX, RotY, RotZ.

*Note that only the absolute path is no longer outputted, only the file's basename*
*Jupyter Notebook may show an additional space between the "[" and "INFO" for subject level info*