v0.1.0

🚀 IntelliCage Analysis Toolkit v0.1.0

September 3, 2026

This is a major architectural update that generalizes the project from a place-learning-only package into the IntelliCage Analysis Toolkit. We renamed the project from ic-placelearning to ic-analysis, moved the public import package to ic_analysis, and converted the workflow to a generic object-oriented experiment API. The release also separates technical IntelliCage export blocks from biological analysis phases: raw export folders are concatenated during loading, while phase assignment comes from subject-level time_window definitions.

We highly recommend to upgrade to this release, as it will be the basis for future development and new experiment modules. The API has changed, so please check the updated documentation and example scripts for guidance on how to adapt your own analysis scripts.

✨ Features

• Renamed the package to ic-analysis and the import package to ic_analysis.
• Added script-defined ExperimentMetadata, PhaseMetadata, SubjectMetadata, and SubjectRegistry classes.
• Added the public ic.experiment(EXPERIMENT=..., PHASES=..., SUBJECTS=...) entry point, returning a generic IntelliCageExperiment object.
• Added modular experiment methods such as .load(), .prepare_analysis(), .plot_ages(), .plot_mice_activity(), .plot_phase_activity_summary(), .plot_NP_adaptation(), .plot_NP_counts(), .plot_licking_counts(), and .plot_bottle_preference().
• Added modular PL/PR-specific methods with the plot_plr_* prefix for learning rates, learning counts, error rates, day-wise endpoints, reversal components, threshold onsets, experience-learning curves, derived ratios, and cumulative corner preferences.
• Added subject-driven inclusion policy: only raw IntelliCage animal IDs with a matching subject metadata entry are analyzed when subject metadata is passed.
• Added support for subject-level phase windows and automatic schedule inference from those windows.
• Added export-block-agnostic loading: each cage-run folder may contain one long export block, several interrupted export blocks, or export blocks that happen to match protocol phases.
• Added subject YAML helper functions to generate editable templates from detected raw animal IDs and load edited subject metadata back into scripts.
• Added a generic bottle-preference analysis for left/right bottle consumption and relative preference ratios.

🧩 Changes

• Removed the all-in-one public analysis workflow in favor of explicit modular plot and analysis calls controlled by the user script.
• Replaced the old user_scripts/analyze_synthetic_group_ab.py script with user_scripts/place_learning_example.py, written as a VS Code interactive script that can be run cell by cell.
• Removed any reliance on Mice.txt; subject metadata now comes from the user script or an edited subject YAML file.
• Renamed the generic phase-activity endpoint from plot_plr_phase_activity_summary() to plot_phase_activity_summary().
• Updated package metadata, repository links, CI import checks, README, and RTD references from ic-placelearning/ic_placelearning to ic-analysis/ic_analysis.

🧪 Tests

• Added tests for metadata validation, subject-registry schedule inference,
  subject-based loader filtering, and experiment-object loading.
• Added tests for export-block-agnostic loading, including a single long export
  block that is split into biological phases by subject-level time windows.
• Kept the full public synthetic workflow test and maintained coverage above
  the 75% threshold.