Quick setup

Quick setup#

Welcome to circStudio, a Python package for reproducible preprocessing, modeling, and analysis of actigraphy time series in biological rhythm research workflows.

Requirements#

  • Python ≥ 3.12.

You can check your Python version with:

python --version

Installation#

Install the latest stable version from PyPI:

pip install circStudio

(Optional) Installation in an Isolated Environment#

To avoid dependency conflicts and ensure a clean, reproducible setup, install circStudio in a dedicated Python environment.

Using Conda/Miniconda:#

conda create -n csenv python=3.12 # Create environment (v. 3.12 or 3.13)
conda activate csenv # Activate environment
python -m pip install circStudio # Install circStudio
conda deactivate # Deactivate environment

Using venv#

# MacOS / Linux
python3 -m venv csenv/ # Create environment
source csenv/bin/activate # Activate the environment
python -m pip install circStudio # Install circStudio
deactivate # Deactivate environment

# Windows (PowerShell)
PS> py -m venv csenv\ # Create environment
PS> csenv\Scripts\activate # Activate environment
PS> python -m pip install circStudio # Install circStudio
PS> deactivate # Deactivate environment

Verify installation#

After installation, confirm that circStudio can be imported:

python -c "import circstudio; print('circstudio imports')"

Sample usage#

The example below illustrates a minimal workflow for loading actigraphy data and computing a basic metric:

import pandas as pd
import circstudio as cs
import os

# Load sample actigraphy time series
data_dir = os.path.join(os.path.dirname(cs.__file__), "data")
raw = cs.io.read_atr(os.path.join(data_dir, 'test_sample_atr.txt'))

# Alternative: load a generic actigraphy file using pandas
# Expected columns: timestamp, activity (and optionally temperature, light)
#raw = pd.read_csv("example_actigraphy.csv", parse_dates=["timestamp"])

# Compute intradaily variability (IV)
iv = cs.analysis.IV(data=raw.activity)

print(f"Intradaily variability: {iv:.2f}")

Intradaily variability: 0.56

Next steps#

In the following tutorials, you will learn how to:

  • Use adaptor classes to load common actigraphy file formats.

  • Work directly with the Raw class to import and preprocess custom actigraphy data.

  • Compute widely used actigraphy-derived metrics.

  • Perform automatic rest/sleep detection.

  • Apply mathematical models to characterize circadian rhythms and extract mechanistic insights from behavioral time series.