analysis_utils

Reusable Python utilities for scientific and neural data analysis.

The distribution name is analysis-utils; the Python import name is analysis_utils. Version 0.1.0 directly replaces the former utils package without a compatibility namespace.

Installation

Install the core package:

python -m pip install -e .

Install the core test dependency:

python -m pip install -e ".[test]"
python -m pytest -q -m "not neuropred"

Repository analysis scripts additionally use PyTorch and plotting/image libraries:

python -m pip install -e ".[scripts,test]"

The scripts also require the separately maintained neuro-predictor package. Install its checkout in the active environment; it is intentionally not a core dependency of analysis-utils.

Modules and array conventions

Module	Public functions	Main array conventions
analysis_utils.io	load_goodunit_response, load_goodunit_unit_metadata, merge_goodunit_files	Responses use (n_stimuli, n_units), (n_stimuli, n_time, n_units), or (n_trials, n_units) depending on mode.
analysis_utils.metrics	pearson_by_target, explained_variance_by_target, correct_by_noise_ceiling, score_predictions, split_half_reliability	Prediction inputs default to (n_samples, n_targets) and return one value per target.
analysis_utils.cv	ridge_predict, ridge_cv_fit_predict, ridge_cv_predict, pls_predict, nested_ridge_cv, nested_pls_cv	Features use (n_samples, n_features); targets use (n_samples,) or (n_samples, n_targets).
analysis_utils.neural	compute_dprime, select_neurons	Selection operates on one value per unit and returns a mask, indices, summary, and optional selected responses.

Detailed assumptions and return values are documented in each function's docstring.

Core API

from analysis_utils import (
    compute_dprime,
    correct_by_noise_ceiling,
    explained_variance_by_target,
    load_goodunit_response,
    load_goodunit_unit_metadata,
    merge_goodunit_files,
    nested_pls_cv,
    nested_ridge_cv,
    pearson_by_target,
    pls_predict,
    ridge_cv_fit_predict,
    ridge_cv_predict,
    ridge_predict,
    score_predictions,
    select_neurons,
    split_half_reliability,
)

Cross-validation modes

legacy PCA fits PCA before cross-validation to reproduce historical analyses. leakage_free PCA fits preprocessing inside each training fold and is the recommended mode for new analyses. Nested Ridge and PLS functions select hyperparameters using inner folds and report outer-fold predictions.

Repository scripts

Machine-specific inputs are explicit CLI arguments. Numerical defaults such as model layers, time windows, cross-validation folds, and random seeds remain unchanged.

python scripts/FeatureExtracting.py `
    --image-folder <images> `
    --checkpoint <weights>

python scripts/LayerSearch.py `
    --image-folder <images> `
    --neural-path <responses.npz> `
    --checkpoint <weights>

python scripts/run_resnet50_layer_search_encoding.py `
    --goodunit-path <goodunit.mat> `
    --image-folder <images> `
    --smoke-test

See the migration guide for the breaking import change and the validation report for numerical comparison results.