### Clone and Setup Repository

Source: https://github.com/adamma-cdhi-eth-zurich/cosinorage/blob/main/README.md

Commands to clone the source code and prepare the local environment.

```bash
git clone https://github.com/yourusername/cosinorage.git
cd cosinorage
```

```bash
# Create a new virtual environment
python -m venv venv

# Activate the virtual environment
# On Windows:
venv\Scripts\activate
# On macOS/Linux:
source venv/bin/activate
```

```bash
# Upgrade pip
pip install --upgrade pip

# Install required packages
pip install -r requirements.txt
```

```bash
# Install in development mode
pip install -e .
```

--------------------------------

### Build Package

Source: https://github.com/adamma-cdhi-eth-zurich/cosinorage/blob/main/README.md

Install the build package and then run the build command to create distributable artifacts for the package.

```bash
pip install build
python -m build
```

--------------------------------

### Initialize GalaxyDataHandler

Source: https://github.com/adamma-cdhi-eth-zurich/cosinorage/blob/main/README.md

Example of configuring the GalaxyDataHandler with specific directory paths and preprocessing arguments.

```python
galaxy_handler = GalaxyDataHandler(gw_file_dir='../data/smartwatch/GalaxyWatch_Case1/', preprocess=True, preprocess_args=preprocess_args, verbose=True)
```

--------------------------------

### Install CosinorAge via pip

Source: https://github.com/adamma-cdhi-eth-zurich/cosinorage/blob/main/README.md

Recommended method for installing the package using the Python package installer.

```bash
pip install cosinorage
```

--------------------------------

### Upload Package to PyPI

Source: https://github.com/adamma-cdhi-eth-zurich/cosinorage/blob/main/README.md

Install twine for uploading and then use it to upload the built distribution files to the PyPI repository.

```bash
pip install twine
twine upload dist/*
```

--------------------------------

### Quick Start with CosinorAge

Source: https://github.com/adamma-cdhi-eth-zurich/cosinorage/blob/main/README.md

Basic workflow for initializing a data handler, extracting features, and generating biological age predictions.

```python
import cosinorage
from cosinorage.datahandlers import GalaxyDataHandler

# Initialize a data handler
handler = GalaxyDataHandler(galaxy_file_dir='path/to/your/data')

# Compute features
from cosinorage.features import WearableFeatures, dashboard
features = WearableFeatures(handler)
dashboard(features)

# Compute CosinorAge (dummy data)
from cosinorage.bioages import CosinorAge
records = [
    {'handler': handler, 
     'age': 60, 
     'gender': 'male', 
    }
]
predictions = CosinorAge(records)
predictions.get_predictions()
```

--------------------------------

### Initialize BulkWearableFeatures for Cosinor Age Analysis

Source: https://github.com/adamma-cdhi-eth-zurich/cosinorage/blob/main/examples/bulk_example.ipynb

Initializes the BulkWearableFeatures class with specified handlers, feature arguments, and cosinor age input data. This setup is crucial for batch processing and feature computation.

```python
handlers = [generic_handler1, generic_handler2, generic_handler3]
cosinor_age_inputs = [{'gender': 'male', 'age': 20, 'gt_cosinor_age': 30}, {'gender': 'female', 'age': 20, 'gt_cosinor_age': 30}, {'gender': 'unknown', 'age': 20, 'gt_cosinor_age': 30}] 
bulk_features = BulkWearableFeatures(
    handlers=handlers, 
    features_args=features_args,
    cosinor_age_inputs=cosinor_age_inputs, 
    compute_distributions=True
    )
```

--------------------------------

### M10(data)

Source: https://github.com/adamma-cdhi-eth-zurich/cosinorage/blob/main/docs/source/cosinorage.features.md

Calculates the M10 (mean activity during the 10 most active hours) and the start time of the 10 most active hours for each day.

```APIDOC
## POST /M10

### Description
Calculate the M10 (mean activity during the 10 most active hours) and the start time of the 10 most active hours (M10_start) for each day.

### Parameters
#### Request Body
- **data** (pd.Series) - Required - Time series data containing activity measurements with datetime index and ‘ENMO’ column.

### Response
#### Success Response (200)
- **m10** (List[float]) - List of mean activity values during the 10 most active hours for each day.
- **m10_start** (List[datetime]) - List of start times of the 10 most active hours for each day.
```

--------------------------------

### Prepare Input Data for CosinorAge Object

Source: https://github.com/adamma-cdhi-eth-zurich/cosinorage/blob/main/examples/nhanes_example.ipynb

Structures the input data for the CosinorAge object, including the data handler, chronological age, gender, and ground truth Cosinor age. Note: Gender is set to 'unknown' in this example.

```python
records = [
    {'handler': nhanes_handler, 
     'age': get_chrono_age_and_gender('../data/Age_sex_data/nhanes_age_sex.csv', 62177)[0], 
     'gender': 'unknown',

```

--------------------------------

### Initialize and Compute Bulk Wearable Features

Source: https://github.com/adamma-cdhi-eth-zurich/cosinorage/blob/main/docs/source/cosinorage.features.md

Demonstrates initializing BulkWearableFeatures with multiple handlers and CosinorAge inputs, then retrieving statistical summaries and checking for failures. Ensure DataHandlers are loaded before initialization.

```python
from cosinorage.datahandlers import GalaxyDataHandler
from cosinorage.features import BulkWearableFeatures

# Create multiple handlers
handlers = []
for i in range(3):
    handler = GalaxyDataHandler(f"data/participant_{i}.csv")
    handler.load_data()
    handlers.append(handler)

# Define age and gender information for CosinorAge computation
cosinor_age_inputs = [
    {"age": 25.5, "gender": "female", "gt_cosinor_age": 26.2},
    {"age": 30.2, "gender": "male", "gt_cosinor_age": 31.1},
    {"age": 28.0, "gender": "unknown", "gt_cosinor_age": 27.8}
]

# Compute bulk features with CosinorAge
bulk = BulkWearableFeatures(
    handlers,
    compute_distributions=True,
    cosinor_age_inputs=cosinor_age_inputs
)

# Get statistical summary (includes CosinorAge features)
stats = bulk.get_distribution_stats()
print(f"Computed features for {len(stats)} feature types")

# Check for failures
failed = bulk.get_failed_handlers()
if failed:
    print(f"Failed handlers: {len(failed)}")
```

--------------------------------

### Read Galaxy CSV Data

Source: https://github.com/adamma-cdhi-eth-zurich/cosinorage/blob/main/docs/source/cosinorage.datahandlers.md

Example of loading ENMO data from a Galaxy Watch CSV file.

```APIDOC
## Load ENMO data from Galaxy Watch CSV file

### Description
This example demonstrates how to load ENMO data from a specified Galaxy Watch CSV file, including handling metadata and selecting specific data columns.

### Parameters
- **galaxy_file_path** (string) - Path to the Galaxy Watch CSV file.
- **meta_dict** (dict) - Dictionary to store metadata. Will be updated with sampling frequency.
- **time_column** (string) - The name of the column containing timestamps.
- **data_columns** (list of strings) - List of columns to load as data.
- **verbose** (bool) - If True, prints progress information.

### Request Example
```python
import pandas as pd

meta_dict = {}
data = read_galaxy_csv_data(
    galaxy_file_path='data/galaxy_enmo.csv',
    meta_dict=meta_dict,
    time_column='time',
    data_columns=['enmo_mg'],
    verbose=True
)
print(f"Loaded {len(data)} ENMO records")
print(f"Sampling frequency: {meta_dict['sf']:.1f} Hz")
```
```

--------------------------------

### Initialize CosinorAge Environment

Source: https://github.com/adamma-cdhi-eth-zurich/cosinorage/blob/main/examples/generic_example copy.ipynb

Import necessary modules and configure the notebook environment for autoreloading.

```python
import dill as pickle
from cosinorage.datahandlers import GenericDataHandler, plot_enmo
from cosinorage.features import WearableFeatures, dashboard, BulkWearableFeatures
from cosinorage.bioages import CosinorAge

%load_ext autoreload
%autoreload 2
```

--------------------------------

### Calculate Sleep Onset Latency (SOL)

Source: https://github.com/adamma-cdhi-eth-zurich/cosinorage/blob/main/docs/source/cosinorage.features.md

Measures the time taken to fall asleep from the start of the recording.

```pycon
>>> import pandas as pd
>>>
>>> # Create sample sleep data for one day
>>> dates = pd.date_range('2023-01-01', periods=1440, freq='min')
>>> # Simulate 30 minutes to fall asleep
>>> sleep_pattern = [0] * 30 + [1] * 1410  # 30 min wake, then sleep
>>> data = pd.DataFrame({'sleep': sleep_pattern}, index=dates)
>>>
>>> # Calculate SOL
>>> sol_values = SOL(data)
>>> print(f"Sleep Onset Latency: {sol_values[0]} minutes")
```

--------------------------------

### Initialize UKBDataHandler

Source: https://github.com/adamma-cdhi-eth-zurich/cosinorage/blob/main/README.md

Instantiate the handler for UK Biobank data, requiring paths to quality control files and raw ENMO data.

```python
ukb_handler = UKBDataHandler(qa_file_path='../data/ukb/UKB Acc Quality Control.csv', ukb_file_dir='../data/ukb/UKB Sample Data/1_raw5sec_long', eid=1234567, verbose=True)
```

--------------------------------

### Initialize and Compute Bulk Wearable Features

Source: https://github.com/adamma-cdhi-eth-zurich/cosinorage/blob/main/docs/source/cosinorage.features.md

Create multiple `GalaxyDataHandler` instances, load data, and then initialize `BulkWearableFeatures` to compute distributions and CosinorAge features. This is useful for processing data from multiple participants.

```python
>>> from cosinorage.datahandlers import GalaxyDataHandler
>>> from cosinorage.features import BulkWearableFeatures
>>> 
>>> # Create multiple handlers
>>> handlers = []
>>> for i in range(3):
...     handler = GalaxyDataHandler(f"data/participant_{i}.csv")
...     handler.load_data()
...     handlers.append(handler)
>>> 
>>> # Define age and gender information for CosinorAge computation
>>> cosinor_age_inputs = [
...     {"age": 25.5, "gender": "female", "gt_cosinor_age": 26.2},
...     {"age": 30.2, "gender": "male", "gt_cosinor_age": 31.1},
...     {"age": 28.0, "gender": "unknown", "gt_cosinor_age": 27.8}
... ]
>>> 
>>> # Compute bulk features with CosinorAge
>>> bulk = BulkWearableFeatures(
...     handlers,
...     compute_distributions=True,
...     cosinor_age_inputs=cosinor_age_inputs
... )
>>> 
>>> # Get statistical summary (includes CosinorAge features)
>>> stats = bulk.get_distribution_stats()
>>> print(f"Computed features for {len(stats)} feature types")
>>> 
>>> # Check for failures
>>> failed = bulk.get_failed_handlers()
>>> if failed:
...     print(f"Failed handlers: {len(failed)}")
```

--------------------------------

### Get Cosinor Features

Source: https://github.com/adamma-cdhi-eth-zurich/cosinorage/blob/main/examples/galaxy_binary_example.ipynb

Retrieves features for cosinor analysis. This function is typically used to access the processed data for further analysis.

```python
features.get_features()
```

--------------------------------

### Initialize Libraries and Autoreload

Source: https://github.com/adamma-cdhi-eth-zurich/cosinorage/blob/main/examples/generic_example.ipynb

Load necessary modules for data handling, feature extraction, and plotting, while enabling autoreload for development.

```python
import dill as pickle
from cosinorage.datahandlers import GenericDataHandler, plot_enmo
from cosinorage.features import WearableFeatures, dashboard
from cosinorage.bioages import CosinorAge

%load_ext autoreload
%autoreload 2
```

--------------------------------

### Load Libraries for Galaxy Watch Demo

Source: https://github.com/adamma-cdhi-eth-zurich/cosinorage/blob/main/examples/galaxy_binary_example.ipynb

Imports necessary libraries including dill for pickling, Cosinorage modules for data handling and feature extraction, and IPython extensions for code reloading.

```python
import dill as pickle
from cosinorage.datahandlers import GalaxyDataHandler, plot_enmo
from cosinorage.features import WearableFeatures, dashboard
from cosinorage.bioages import CosinorAge

%load_ext autoreload
%autoreload 2
```

--------------------------------

### L5(data)

Source: https://github.com/adamma-cdhi-eth-zurich/cosinorage/blob/main/docs/source/cosinorage.features.md

Calculates the mean activity during the 5 least active hours and the start time of this period for each day, typically representing the main rest phase.

```APIDOC
## L5(data)

### Description
Calculate the L5 (mean activity during the 5 least active hours) and the start time of the 5 least active hours (L5_start) for each day.

### Parameters
- **data** (pd.Series) - Required - Time series data containing activity measurements with datetime index and 'ENMO' column.

### Response
- **l5** (list) - List of mean activity values during the 5 least active hours for each day.
- **l5_start** (list) - List of start times (datetime) of the 5 least active hours for each day.
```

--------------------------------

### Calculate L5 Circadian Metric

Source: https://github.com/adamma-cdhi-eth-zurich/cosinorage/blob/main/docs/source/cosinorage.features.md

Calculates the mean activity and start time for the 5 least active hours, typically representing the main rest phase.

```pycon
>>> import pandas as pd
>>> import numpy as np
>>>
>>> # Create sample multi-day activity data
>>> dates = pd.date_range('2023-01-01', periods=4320, freq='min')  # 3 days
>>> # Simulate activity with low during night
>>> hours = dates.hour
>>> enmo = pd.Series(np.sin(hours * np.pi / 12) + 1 + np.random.normal(0, 0.1, 4320), index=dates)
>>>
>>> # Calculate L5 for each day
>>> l5_values, l5_starts = L5(enmo)
>>> print(f"L5 values: {l5_values}")
>>> print(f"L5 start times: {l5_starts}")
```

--------------------------------

### Initialize NHANESDataHandler

Source: https://github.com/adamma-cdhi-eth-zurich/cosinorage/blob/main/README.md

Instantiate the handler for NHANES study data by specifying the directory and person ID.

```python
nhanes_handler = NHANESDataHandler(nhanes_file_dir='../data/nhanes/', person_id=62164, verbose=True)
```

--------------------------------

### BulkWearableFeatures Initialization

Source: https://github.com/adamma-cdhi-eth-zurich/cosinorage/blob/main/docs/source/cosinorage.features.md

Initializes BulkWearableFeatures with a list of DataHandler instances and optional arguments for feature computation and distribution analysis.

```APIDOC
## BulkWearableFeatures.__init__

### Description
Initialize BulkWearableFeatures with multiple DataHandler instances.

### Method
__init__

### Parameters
#### Parameters
- **handlers** (List[DataHandler]) - Required - List of DataHandler instances containing ENMO data. Each handler should have been properly initialized and loaded with data.
- **features_args** (dict, optional) - Arguments for feature computation passed to WearableFeatures. Common arguments include: ‘pa_params’: Physical activity parameters, ‘sleep_params’: Sleep detection parameters. Defaults to empty dict.
- **compute_distributions** (bool, optional) - Whether to compute statistical distributions across all features. If False, only individual features are computed. Defaults to True.
- **cosinor_age_inputs** (List[dict] | None) - Optional - Define age and gender information for CosinorAge computation.

### Notes
Empty handlers list is allowed and will result in empty individual_features and distribution_stats.
```

--------------------------------

### Get Cosinor Age Predictions

Source: https://github.com/adamma-cdhi-eth-zurich/cosinorage/blob/main/examples/galaxy_binary_example.ipynb

Retrieves the detailed predictions from the CosinorAge model. The output includes handler information, input features, and calculated cosinor metrics.

```python
cosinor_age.get_predictions()
```

--------------------------------

### Get Summary DataFrame of Statistics

Source: https://github.com/adamma-cdhi-eth-zurich/cosinorage/blob/main/docs/source/cosinorage.features.md

Convert the computed statistical distributions into a pandas DataFrame for easier analysis and export. The DataFrame includes features as rows and various statistics as columns.

```python
>>> import pandas as pd
>>> summary_df = bulk.get_summary_dataframe()
>>> print(summary_df.head())
```

--------------------------------

### Get Distribution Statistics for Features

Source: https://github.com/adamma-cdhi-eth-zurich/cosinorage/blob/main/docs/source/cosinorage.features.md

Obtain statistical distributions across all successfully computed features. This provides aggregated statistics like mean, standard deviation, and quartiles for each feature type.

```python
>>> stats = bulk.get_distribution_stats()
>>> mesor_stats = stats['cosinor_mesor']
>>> print(f"MESOR: mean={mesor_stats['mean']:.3f}, std={mesor_stats['std']:.3f}")
```

--------------------------------

### Initialize Wearable Features

Source: https://github.com/adamma-cdhi-eth-zurich/cosinorage/blob/main/examples/generic_example.ipynb

Sets up the WearableFeatures class with a data handler and specific arguments for feature extraction. This includes hyperparameters for sleep and physical activity detection.

```python
features_args = {
    'sleep_ck_sf': 0.05,
    'sleep_rescore': True,
    'pa_cutpoint_sl': 15,
    'pa_cutpoint_lm': 35,
    'pa_cutpoint_mv': 70,
}

features = WearableFeatures(generic_handler, features_args)
```

--------------------------------

### Get NHANES Metadata

Source: https://github.com/adamma-cdhi-eth-zurich/cosinorage/blob/main/examples/nhanes_example.ipynb

Retrieves and prints metadata associated with the loaded NHANES data, including data source, number of data points, time range, frequency, type, and units.

```python
nhanes_handler.get_meta_data()
```

--------------------------------

### Initialize GenericDataHandler Instances

Source: https://github.com/adamma-cdhi-eth-zurich/cosinorage/blob/main/examples/bulk_example.ipynb

Creates three instances of GenericDataHandler, each configured to load and preprocess a specific accelerometer data CSV file with the defined preprocessing arguments.

```python
generic_handler1 = GenericDataHandler(file_path='../data/public data/processed/watch_acc/1155FF54-63D3-4AB2-9863-8385D0BD0A13_watch_acc.csv', 
                                            data_format='csv',
                                            data_type='accelerometer-mg',
                                            time_format='unix-s',
                                            time_column='timestamp',
                                            data_columns=['x', 'y', 'z'],
                                            preprocess_args=preprocess_args,
                                            verbose=True
                                            )

generic_handler2 = GenericDataHandler(file_path='../data/public data/processed/watch_acc/1DBB0F6F-1F81-4A50-9DF4-CD62ACFA4842_watch_acc.csv', 
                                            data_format='csv',
                                            data_type='accelerometer-mg',
                                            time_format='unix-s',
                                            time_column='timestamp',
                                            data_columns=['x', 'y', 'z'],
                                            preprocess_args=preprocess_args,
                                            verbose=True
                                            )

generic_handler3 = GenericDataHandler(file_path='../data/public data/processed/watch_acc/78A91A4E-4A51-4065-BDA7-94755F0BB3BB_watch_acc.csv', 
                                            data_format='csv',
                                            data_type='accelerometer-mg',
                                            time_format='unix-s',
                                            time_column='timestamp',
                                            data_columns=['x', 'y', 'z'],
                                            preprocess_args=preprocess_args,
                                            verbose=True
                                            )                                            
```

--------------------------------

### Get Individual Features from Handlers

Source: https://github.com/adamma-cdhi-eth-zurich/cosinorage/blob/main/docs/source/cosinorage.features.md

Retrieve the computed feature dictionaries for each individual handler. Failed computations will be represented as `None` entries in the list. Access specific features like 'MESOR' from the 'cosinor' category.

```python
>>> features = bulk.get_individual_features()
>>> for i, feat in enumerate(features):
...     if feat is not None:
...         print(f"Handler {i}: MESOR = {feat['cosinor']['mesor']:.3f}")
...     else:
...         print(f"Handler {i}: Failed")
```

--------------------------------

### BulkWearableFeatures Initialization

Source: https://github.com/adamma-cdhi-eth-zurich/cosinorage/blob/main/docs/source/cosinorage.features.md

Initializes the BulkWearableFeatures class with a list of DataHandler instances and optional arguments for feature computation and distribution analysis.

```APIDOC
## BulkWearableFeatures Class

### Description
A class for computing and managing features from multiple wearable accelerometer datasets. This class processes multiple DataHandler instances to compute features for each and then calculates statistical distributions (mean, std, quartiles, etc.) across all datasets. It provides comprehensive analysis capabilities for cohort studies and large-scale wearable data analysis.

### Parameters
#### handlers
- **handlers** (List[DataHandler]) - Required - List of DataHandler instances containing ENMO data. Each handler should have been properly initialized and loaded with data.
#### features_args
- **features_args** (dict) - Optional - Arguments for feature computation passed to WearableFeatures. Common arguments include: ‘pa_params’: Physical activity parameters, ‘sleep_params’: Sleep detection parameters. Defaults to empty dict.
#### cosinor_age_inputs
- **cosinor_age_inputs** (List[dict] | None) - Optional - List of dictionaries containing age and gender information for CosinorAge computation. Each dictionary should contain: ‘age’: Chronological age (float), ‘gender’: Gender (‘male’, ‘female’, or ‘unknown’, optional, defaults to ‘unknown’), ‘gt_cosinor_age’: Ground truth cosinor age (float, optional). Must be the same length as handlers if provided. If all dictionaries contain ‘gt_cosinor_age’, a ‘cosinor_age_prediction_error’ feature will be computed. Defaults to None.
#### compute_distributions
- **compute_distributions** (bool) - Optional - Whether to compute statistical distributions across all features. If False, only individual features are computed. Defaults to True.

### Attributes
#### handlers
- **handlers** (List[DataHandler]) - List of DataHandler instances provided during initialization
#### features_args
- **features_args** (dict) - Arguments for feature computation
#### cosinor_age_inputs
- **cosinor_age_inputs** (List[dict]) - List of age/gender dictionaries for CosinorAge computation
#### individual_features
- **individual_features** (List[dict]) - List of feature dictionaries for each handler. Failed computations are represented as None.
#### distribution_stats
- **distribution_stats** (dict) - Statistical distributions across all features. Only populated if compute_distributions=True.
#### failed_handlers
- **failed_handlers** (List[tuple]) - List of (handler_index, error_message) tuples for handlers that failed during feature computation.

### Example
```python
from cosinorage.datahandlers import GalaxyDataHandler
from cosinorage.features import BulkWearableFeatures

# Create multiple handlers
handlers = []
for i in range(3):
    handler = GalaxyDataHandler(f"data/participant_{i}.csv")
    handler.load_data()
    handlers.append(handler)

# Define age and gender information for CosinorAge computation
cosinor_age_inputs = [
    {"age": 25.5, "gender": "female", "gt_cosinor_age": 26.2},
    {"age": 30.2, "gender": "male", "gt_cosinor_age": 31.1},
    {"age": 28.0, "gender": "unknown", "gt_cosinor_age": 27.8}
]

# Compute bulk features with CosinorAge
bulk = BulkWearableFeatures(
    handlers,
    compute_distributions=True,
    cosinor_age_inputs=cosinor_age_inputs
)

# Get statistical summary (includes CosinorAge features)
stats = bulk.get_distribution_stats()
print(f"Computed features for {len(stats)} feature types")

# Check for failures
failed = bulk.get_failed_handlers()
if failed:
    print(f"Failed handlers: {len(failed)}")
```
```

--------------------------------

### Load Libraries for NHANES Demo

Source: https://github.com/adamma-cdhi-eth-zurich/cosinorage/blob/main/examples/nhanes_example.ipynb

Imports necessary libraries for data handling, feature extraction, plotting, and biological age calculation. Includes autoreload for development.

```python
import dill as pickle
from cosinorage.datahandlers import NHANESDataHandler, plot_enmo
from cosinorage.features import WearableFeatures, dashboard
from cosinorage.bioages import CosinorAge

%load_ext autoreload
%autoreload 2
```

--------------------------------

### Initialize WearableFeatures Class

Source: https://github.com/adamma-cdhi-eth-zurich/cosinorage/blob/main/docs/source/theoretical_background.md

Instantiates the WearableFeatures class, which computes various wearable-derived features from minute-level ENMO data. Requires a DataHandler object and accepts optional feature computation hyperparameters.

```python
import pandas as pd

class WearableFeatures():
    def __init__(self, 
        handler: DataHandler,
        features_args: dict = {}):

        self.ml_data = handler.get_ml_data()

        self.feature_df = pd.DataFrame()
        self.feature_dict = {}

        self.__run()
```

--------------------------------

### Calculate NHANES Measurement Timestamp

Source: https://github.com/adamma-cdhi-eth-zurich/cosinorage/blob/main/docs/source/cosinorage.datahandlers.md

Convert NHANES timing information into datetime objects. This function combines a start time string with seconds since midnight, applying a scaling factor to calculate the precise measurement timestamp.

```python
>>> import pandas as pd
>>> 
>>> # Create sample row with timing information
>>> row = pd.Series({
...     'day1_start_time': '08:30:00',
...     'paxssnmp': 8000  # 100 seconds * 80
... })
>>> 
>>> # Calculate measurement time
>>> measure_time = calculate_measure_time(row)
>>> print(f"Measurement time: {measure_time}")
>>> # Output: 1900-01-01 08:31:40 (base time + 100 seconds)
```

--------------------------------

### Load ENMO data from Galaxy Watch CSV

Source: https://github.com/adamma-cdhi-eth-zurich/cosinorage/blob/main/docs/source/cosinorage.datahandlers.md

Loads ENMO data from a specified Galaxy Watch CSV file. Requires the file path and optionally accepts a dictionary to store metadata and specifies which columns to load. Use when starting with raw CSV data.

```python
>>> import pandas as pd
>>> 
>>> # Load ENMO data from Galaxy Watch CSV file
>>> meta_dict = {}
>>> data = read_galaxy_csv_data(
...     galaxy_file_path='data/galaxy_enmo.csv',
...     meta_dict=meta_dict,
...     time_column='time',
...     data_columns=['enmo_mg'],
...     verbose=True
... )
>>> print(f"Loaded {len(data)} ENMO records")
>>> print(f"Sampling frequency: {meta_dict['sf']:.1f} Hz")
```

--------------------------------

### Define Preprocessing Arguments

Source: https://github.com/adamma-cdhi-eth-zurich/cosinorage/blob/main/examples/generic_example.ipynb

Specify parameters for autocalibration, frequency filtering, and wear detection algorithms.

```python
preprocess_args = {
    'autocalib_sd_criter': 0.001,
    'autocalib_sphere_crit': 0.08,
    'filter_type': 'lowpass',
    'filter_cutoff': 2,
    'wear_sd_crit': 0.00013,
    'wear_range_crit': 0.067,
    'wear_window_length': 45,
    'wear_window_skip': 7,
    'required_daily_coverage': 0.25
}
```

--------------------------------

### Load and Pickle Data Handler

Source: https://github.com/adamma-cdhi-eth-zurich/cosinorage/blob/main/examples/generic_example copy.ipynb

Load accelerometer data from a CSV file into a GenericDataHandler and cache the result using pickle.

```python
file_path = '/Users/jacquesleooscar/CO-001.csv'
#file_path = '../data/public data/processed/motion/9618981_acceleration.csv'

if reload:
    generic_handler = GenericDataHandler(file_path=file_path, 
                                            data_format='csv',
                                            data_type='accelerometer-g',
                                            time_format='datetime',
                                            time_column='timestamp',
                                            time_zone=None,
                                            data_columns=['x', 'y', 'z'],
                                            preprocess_args=preprocess_args,
                                            verbose=True
                                            )

    with open("pickle/generic_handler.pkl", "wb") as file:
        pickle.dump(generic_handler, file)
else:
    with open("pickle/generic_handler.pkl", "rb") as file:
        generic_handler = pickle.load(file)
```

--------------------------------

### Define Preprocessing Arguments for GalaxyDataHandler

Source: https://github.com/adamma-cdhi-eth-zurich/cosinorage/blob/main/examples/galaxy_binary_example.ipynb

Configuration dictionary for preprocessing arguments used in the GalaxyDataHandler. Includes settings for autocalibration, frequency filtering, and wear detection.

```python
preprocess_args = {
    'autocalib_sd_criter': 0.01,
    'autocalib_sphere_crit': 0.02,
    'filter_type': 'lowpass',
    'filter_cutoff': 2,
    'wear_sd_crit': 0.00013,
    'wear_range_crit': 0.00067,
    'wear_window_length': 45,
    'wear_window_skip': 7,
    'required_daily_coverage': 0.5
}
```

--------------------------------

### Preprocess accelerometer data with wear detection

Source: https://github.com/adamma-cdhi-eth-zurich/cosinorage/blob/main/docs/source/cosinorage.datahandlers.md

Demonstrates applying calibration, noise removal, and wear detection to a pandas DataFrame containing accelerometer data.

```pycon
>>> import pandas as pd
>>> import numpy as np
>>>
>>> # Create sample accelerometer data
>>> dates = pd.date_range('2023-01-01', periods=1440, freq='min')
>>> data = pd.DataFrame({
...     'x': np.random.randn(1440),
...     'y': np.random.randn(1440),
...     'z': np.random.randn(1440) + 1  # Add gravity component
... }, index=dates)
>>>
>>> # Apply preprocessing with wear detection
>>> preprocess_args = {
...     'calibrate': True,
...     'remove_noise': True,
...     'detect_wear': True
... }
>>> meta_dict = {}
>>> processed_data = preprocess_generic_data(
...     data, data_type='accelerometer',
...     preprocess_args=preprocess_args, meta_dict=meta_dict, verbose=True
... )
>>> print(f"Processed data shape: {processed_data.shape}")
>>> print(f"Wear column present: {'wear' in processed_data.columns}")
```

--------------------------------

### Initialize UKBDataHandler Class

Source: https://github.com/adamma-cdhi-eth-zurich/cosinorage/blob/main/docs/source/theoretical_background.md

The UKBDataHandler class, a subclass of DataHandler, initializes with paths for quality assurance files and UK Biobank data directory, along with an individual's EID. It then calls the __load_data method.

```python
class UKBDataHandler(DataHandler):
    def __init__(self,
        qa_file_path: str,
        ukb_file_dir: str,
        eid: int):

        super().__init__()

        self.qa_file_path = qa_file_path
        self.ukb_file_dir = ukb_file_dir
        self.eid = eid

        self.__load_data()
```

--------------------------------

### CosinorAge Initialization and Prediction

Source: https://github.com/adamma-cdhi-eth-zurich/cosinorage/blob/main/docs/source/cosinorage.bioages.md

Demonstrates how to initialize the CosinorAge class with participant data and retrieve biological age predictions.

```APIDOC
## CosinorAge Initialization (`__init__`)

### Description
Initializes the CosinorAge calculator with a list of participant records and automatically computes biological age predictions.

### Method
`__init__`

### Parameters
#### Request Body
- **records** (List[dict]) - Required - A list of dictionaries, where each dictionary represents a participant record. Each record must contain:
  - **handler** (DataHandler) - Required - An object providing minute-level ENMO data (e.g., GenericDataHandler, GalaxyDataHandler).
  - **age** (float) - Required - The chronological age of the participant.
  - **gender** (str) - Optional - The gender of the participant ('male', 'female', or 'unknown'). Defaults to 'unknown' if not provided.

### Request Example
```python
from cosinorage.bioages import CosinorAge
from cosinorage.datahandlers import GenericDataHandler

# Example record for a single participant
handler = GenericDataHandler(file_path='data/participant_001.csv', data_type='accelerometer-mg', time_column='timestamp', data_columns=['x', 'y', 'z'])
record = {
    'handler': handler,
    'age': 45.5,
    'gender': 'female'
}

# Initialize CosinorAge with the record
cosinor_age = CosinorAge([record])
```

### Response
#### Success Response (Initialization)
Initialization is automatic upon object creation. Predictions are stored internally.

#### Response Example
(No direct response on initialization; predictions are accessed via `get_predictions()`)

## get_predictions()

### Description
Retrieves the computed biological age predictions and cosinor parameters for all processed participant records.

### Method
`get_predictions`

### Endpoint
N/A (This is a method of the CosinorAge class)

### Parameters
None

### Request Example
```python
predictions = cosinor_age.get_predictions()
result = predictions[0]
print(f"Chronological age: {result['age']:.1f}")
print(f"Predicted biological age: {result['cosinorage']:.1f}")
print(f"Age advance: {result['cosinorage_advance']:.1f}")
```

### Response
#### Success Response (200)
- **List[dict]** - A list of dictionaries, where each dictionary represents a participant's prediction results. Each dictionary contains:
  - **handler** (DataHandler) - The original data handler object.
  - **age** (float) - The chronological age.
  - **gender** (str) - The gender of the participant.
  - **mesor** (float) - The MESOR value from cosinor analysis.
  - **amp1** (float) - The amplitude of the primary circadian rhythm.
  - **phi1** (float) - The acrophase of the primary circadian rhythm.
  - **cosinorage** (float) - The predicted biological age.
  - **cosinorage_advance** (float) - The difference between biological and chronological age.

#### Response Example
```json
[
  {
    "handler": "<DataHandler object>",
    "age": 45.5,
    "gender": "female",
    "mesor": 100.5,
    "amp1": 20.2,
    "phi1": 1.5,
    "cosinorage": 48.2,
    "cosinorage_advance": 2.7
  }
]
```
```

--------------------------------

### Initialize GenericDataHandler

Source: https://github.com/adamma-cdhi-eth-zurich/cosinorage/blob/main/README.md

Configure the generic handler for different accelerometer data types by mapping columns and specifying data formats.

```python
generic_handler = GenericDataHandler(
    file_path='data/enmo_data.csv',
    data_type='enmo-mg',
    time_column='timestamp',
    data_columns=['enmo'],
    preprocess_args=preprocess_args,
    verbose=True
)
```

```python
generic_handler = GenericDataHandler(
    file_path='data/accel_data.csv',
    data_type='accelerometer-mg',
    time_column='time',
    data_columns=['x', 'y', 'z'],
    preprocess_args=preprocess_args,
    verbose=True
)
```

--------------------------------

### Import Libraries and Load Extensions

Source: https://github.com/adamma-cdhi-eth-zurich/cosinorage/blob/main/examples/bulk_example.ipynb

Imports necessary modules from the cosinorage library and enables autoreload for development.

```python
from cosinorage.datahandlers import GenericDataHandler
from cosinorage.features import BulkWearableFeatures

%load_ext autoreload
%autoreload 2
```

--------------------------------

### Compute bulk wearable features

Source: https://github.com/adamma-cdhi-eth-zurich/cosinorage/blob/main/examples/generic_example copy.ipynb

Initializes the feature extraction process and retrieves a summary dataframe.

```python
handlers = [generic_handler]

bulk_features = BulkWearableFeatures(
    handlers=handlers, 
    features_args=features_args,
    cosinor_age_inputs=None, 
    compute_distributions=True
    )
bulk_features.get_summary_dataframe()
```

--------------------------------

### Load and Pickle Data Handler

Source: https://github.com/adamma-cdhi-eth-zurich/cosinorage/blob/main/examples/generic_example.ipynb

Load accelerometer data into a GenericDataHandler and persist the object to a pickle file for future use.

```python
file_path = '../data/public data/processed/watch_acc_ml/0A986513-7828-4D53-AA1F-E02D6DF9561B_watch_acc_ml.csv'
#file_path = '../data/public data/processed/motion/9618981_acceleration.csv'

if reload:
    generic_handler = GenericDataHandler(file_path=file_path, 
                                            data_format='csv',
                                            data_type='accelerometer-mg',
                                            time_format='unix-s',
                                            time_column='timestamp',
                                            time_zone="Australia/Sydney",
                                            data_columns=['x', 'y', 'z'],
                                            preprocess_args=preprocess_args,
                                            verbose=True
                                            )

    with open("pickle/generic_handler.pkl", "wb") as file:
        pickle.dump(generic_handler, file)
else:
    with open("pickle/generic_handler.pkl", "rb") as file:
        generic_handler = pickle.load(file)
```

--------------------------------

### Initialize CosinorAge with Records

Source: https://github.com/adamma-cdhi-eth-zurich/cosinorage/blob/main/examples/galaxy_binary_example.ipynb

Initializes the CosinorAge class with a list of records. Each record should contain handler, age, gender, and ground truth cosinor age.

```python
records = [
    {'handler': galaxy_handler_binary, 
     'age': 20, 
     'gender': 'male', 
     'gt_cosinor_age': 22
    }
]
```

--------------------------------

### Detect Wear Periods with detect_wear_periods

Source: https://github.com/adamma-cdhi-eth-zurich/cosinorage/blob/main/docs/source/cosinorage.datahandlers.md

Identifies device wear periods using sliding windows of acceleration data. Requires preprocessed accelerometer data in g units.

```pycon
>>> import pandas as pd
>>> import numpy as np
>>>
>>> # Create sample accelerometer data
>>> timestamps = pd.date_range('2023-01-01', periods=1000, freq='40ms')
>>> data = pd.DataFrame({
...     'x': np.random.normal(0, 0.1, 1000),
...     'y': np.random.normal(0, 0.1, 1000),
...     'z': np.random.normal(1, 0.1, 1000)  # Gravity component
... }, index=timestamps)
>>>
>>> # Detect wear periods
>>> wear_data = detect_wear_periods(
...     data, sf=25, sd_crit=0.013, range_crit=0.05,
...     window_length=60, window_skip=30, verbose=True
... )
>>> print(f"Wear time: {wear_data['wear'].sum() / 25:.1f} seconds")
```

--------------------------------

### UserWarning for Insufficient Data for Calibration

Source: https://github.com/adamma-cdhi-eth-zurich/cosinorage/blob/main/examples/bulk_example.ipynb

This warning indicates that the provided data is less than 72 hours, preventing the calibration process from being performed. Ensure sufficient data duration for accurate calibration.

```python
Output:
/Users/jacquesleooscar/Documents/Education/ETHZ/Curriculum/Semester04/04MasterThesis/CosinorAge/venvCL/lib/python3.10/site-packages/skdh/preprocessing/calibrate.py:163: UserWarning: Less than 72 hours of data (0.1439998632 hours). No Calibration performed
  warn(


```

--------------------------------

### Initialize CosinorAge Records

Source: https://github.com/adamma-cdhi-eth-zurich/cosinorage/blob/main/examples/galaxy_csv_example.ipynb

Defines a list of records containing data handlers and ground truth metadata for age prediction.

```python
records = [
    {'handler': galaxy_handler_csv, 
     'age': 20, 
     'gender': 'male', 
     'gt_cosinor_age': 22
    }
]
```

--------------------------------

### Initialize GenericDataHandler for ENMO data

Source: https://github.com/adamma-cdhi-eth-zurich/cosinorage/blob/main/docs/source/cosinorage.datahandlers.md

Use this snippet to load and process ENMO data from a CSV file. Ensure the file path, data type, time column, and data columns are correctly specified.

```python
handler = GenericDataHandler(
    file_path='data/enmo_data.csv',
    data_type='enmo',
    time_column='timestamp',
    data_columns=['enmo']
)
raw_data = handler.get_raw_data()
ml_data = handler.get_ml_data()
```

--------------------------------

### Initialize CosinorAge Model

Source: https://github.com/adamma-cdhi-eth-zurich/cosinorage/blob/main/examples/generic_example.ipynb

Creates an instance of the CosinorAge model. It requires a list of records, where each record contains a data handler, age, gender, and ground truth cosinor age.

```python
records = [
    {'handler': generic_handler, 
     'age': 40, 
     'gender': 'unknown',
     'gt_cosinor_age': 22
    }
]

cosinor_age = CosinorAge(records)
```

--------------------------------

### Preprocess Galaxy CSV Data

Source: https://github.com/adamma-cdhi-eth-zurich/cosinorage/blob/main/docs/source/cosinorage.datahandlers.md

Demonstrates how to preprocess ENMO data using the preprocess_galaxy_csv_data function. Note that wear detection is currently not implemented for ENMO data.

```pycon
>>> import pandas as pd
>>>
>>> # Create sample ENMO data
>>> dates = pd.date_range('2023-01-01', periods=1440, freq='min')
>>> data = pd.DataFrame({'ENMO': np.random.uniform(0, 0.1, 1440)}, index=dates)
>>>
>>> # Preprocess the data
>>> meta_dict = {}
>>> preprocess_args = {}
>>> processed_data = preprocess_galaxy_csv_data(
...     data, preprocess_args=preprocess_args, meta_dict=meta_dict, verbose=True
... )
>>> print(f"Processed data shape: {processed_data.shape}")
>>> print(f"Wear column present: {'wear' in processed_data.columns}")
```

--------------------------------

### Load and Preprocess Generic Accelerometer Data

Source: https://context7.com/adamma-cdhi-eth-zurich/cosinorage/llms.txt

Use GenericDataHandler to load CSV accelerometer data and apply preprocessing steps like filtering and wear detection.

```python
from cosinorage.datahandlers import GenericDataHandler

# Define preprocessing arguments
preprocess_args = {
    'autocalib_sd_criter': 0.001,
    'autocalib_sphere_crit': 0.08,
    'filter_type': 'lowpass',
    'filter_cutoff': 2,
    'wear_sd_crit': 0.00013,
    'wear_range_crit': 0.067,
    'wear_window_length': 45,
    'wear_window_skip': 7,
    'required_daily_coverage': 0.25
}

# Load accelerometer data from CSV
handler = GenericDataHandler(
    file_path='data/accelerometer_data.csv',
    data_format='csv',
    data_type='accelerometer-mg',  # Options: 'accelerometer-mg', 'accelerometer-g', 'enmo-mg', 'enmo-g'
    time_format='unix-s',          # Options: 'unix-ms', 'unix-s', 'datetime'
    time_column='timestamp',
    time_zone='Australia/Sydney',
    data_columns=['x', 'y', 'z'],
    preprocess_args=preprocess_args,
    verbose=True
)

# Access processed data
ml_data = handler.get_ml_data()      # Minute-level ENMO data
raw_data = handler.get_raw_data()    # Original raw data
sf_data = handler.get_sf_data()      # Filtered data at original frequency
metadata = handler.get_meta_data()   # Processing metadata

print(f"Loaded {metadata['raw_n_datapoints']} data points")
print(f"Date range: {metadata['raw_start_datetime']} to {metadata['raw_end_datetime']}")
print(f"Wear time: {metadata['wear_time']/3600:.1f} hours")
```

--------------------------------

### Initialize GenericDataHandler for Accelerometer data

Source: https://github.com/adamma-cdhi-eth-zurich/cosinorage/blob/main/docs/source/cosinorage.datahandlers.md

Use this snippet to load and process raw accelerometer data (x, y, z) from a CSV file. Specify the file path, data type, time column, and the names of the x, y, and z columns.

```python
handler = GenericDataHandler(
    file_path='data/accel_data.csv',
    data_type='accelerometer',
    time_column='time',
    data_columns=['x', 'y', 'z']
)
raw_data = handler.get_raw_data()
ml_data = handler.get_ml_data()
```

--------------------------------

### Initialize DataHandler Class

Source: https://github.com/adamma-cdhi-eth-zurich/cosinorage/blob/main/docs/source/theoretical_background.md

The base DataHandler class initializes empty DataFrames for raw, sampled, and minute-level data, along with a metadata dictionary. Subclasses must implement the __load_data method.

```python
import pandas as pd

class DataHandler:
    def __init__(self):
        self.raw_data = pd.DataFrame()
        self.sf_data = pd.DataFrame()
        self.ml_data = pd.DataFrame()

        self.meta_dict = {}

    def __load_data(self):
        raise NotImplementedError(
            "__load_data() should be implemented by subclasses"
        )
```

--------------------------------

### Compute and Visualize Wearable Features

Source: https://github.com/adamma-cdhi-eth-zurich/cosinorage/blob/main/README.md

Calculate features from a handler object and generate a dashboard visualization.

```python
features = WearableFeatures(smartwatch_handler)
features.run()
```

```python
dashboard(features)
```

--------------------------------

### Display First Few Rows of ML Data

Source: https://github.com/adamma-cdhi-eth-zurich/cosinorage/blob/main/examples/galaxy_csv_example.ipynb

Shows the head of the machine learning data, which includes timestamp, enmo, wear status, time, cosinor fitted values, and sleep status.

```python
features.get_ml_data().reset_index().head()
```

--------------------------------

### Extract Wearable Features

Source: https://github.com/adamma-cdhi-eth-zurich/cosinorage/blob/main/examples/generic_example copy.ipynb

Initialize the feature extractor with a data handler and arguments, then compute the features.

```python
features = WearableFeatures(generic_handler, features_args)
features.get_features()
```

```python
features.get_features()
```

--------------------------------

### Generate Comprehensive Dashboard

Source: https://github.com/adamma-cdhi-eth-zurich/cosinorage/blob/main/docs/source/cosinorage.features.md

Generates a visualization dashboard for accelerometer data analysis using a WearableFeatures object. Displays cosinor fit, daily ENMO plots, stability metrics, relative amplitude, sleep predictions, sleep metrics, and physical activity breakdown.

```python
>>> from cosinorage.features import WearableFeatures
>>> from cosinorage.datahandlers import GenericDataHandler
>>>
>>> # Load data and compute features
>>> handler = GenericDataHandler('data.csv')
>>> features = WearableFeatures(handler)
>>>
>>> # Generate comprehensive dashboard
>>> dashboard(features)
```

--------------------------------

### Initialize WearableFeatures

Source: https://github.com/adamma-cdhi-eth-zurich/cosinorage/blob/main/docs/source/cosinorage.features.md

Initializes the WearableFeatures class with a DataHandler instance and optional feature arguments. This class computes and manages features from wearable accelerometer data, including circadian rhythm and physical activity metrics.

```python
>>> from cosinorage.features import WearableFeatures
>>> from cosinorage.datahandlers import GenericDataHandler
>>>
>>> # Load data and compute features
>>> handler = GenericDataHandler('data.csv')
>>> features = WearableFeatures(handler)
```

--------------------------------

### Generate Dashboard

Source: https://github.com/adamma-cdhi-eth-zurich/cosinorage/blob/main/docs/source/cosinorage.features.md

Creates a comprehensive visualization dashboard for accelerometer data analysis, including cosinor fit, daily ENMO, stability metrics, and sleep analysis.

```APIDOC
## dashboard(features)

### Description
Generate a comprehensive visualization dashboard for accelerometer data analysis. This function creates multiple plots to visualize various aspects of the accelerometer data: 1. Cosinor fit plot showing ENMO data with mesor, amplitude, and acrophase 2. Daily ENMO plots with M10 and L5 periods highlighted 3. IS (Inter-daily Stability) and IV (Intra-daily Variability) visualization 4. RA (Relative Amplitude) plots for each day 5. Sleep predictions visualization 6. Sleep metrics (TST, WASO, PTA, NWB, SOL) visualization 7. Physical activity breakdown by intensity levels

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
* **features** ([*WearableFeatures*](#cosinorage.features.WearableFeatures)) – A WearableFeatures object containing all extracted features and raw data. Expected to have the following attributes:
    - feature_dict: Dictionary containing cosinor, nonparam, sleep, and physical_activity features
    - get_ml_data(): Method returning DataFrame with ENMO and cosinor_fitted data
    - get_features(): Method returning all extracted features

### Response
#### Success Response (200)
Displays multiple matplotlib figures using plt.show()

#### Response Example
None
```

--------------------------------

### Compute biological age for a single participant

Source: https://github.com/adamma-cdhi-eth-zurich/cosinorage/blob/main/docs/source/cosinorage.bioages.md

Demonstrates initializing a data handler and computing biological age predictions for one individual.

```pycon
>>> from cosinorage.bioages import CosinorAge
>>> from cosinorage.datahandlers import GenericDataHandler
>>>
>>> # Create a data handler with accelerometer data
>>> handler = GenericDataHandler(
...     file_path='data/participant_001.csv',
...     data_type='accelerometer-mg',
...     time_column='timestamp',
...     data_columns=['x', 'y', 'z']
... )
>>>
>>> # Create a record with age and gender information
>>> record = {
...     'handler': handler,
...     'age': 45.5,
...     'gender': 'female'
... }
>>>
>>> # Compute CosinorAge predictions
>>> cosinor_age = CosinorAge([record])
>>> predictions = cosinor_age.get_predictions()
>>>
>>> # Access the results
>>> result = predictions[0]
>>> print(f"Chronological age: {result['age']:.1f}")
>>> print(f"Predicted biological age: {result['cosinorage']:.1f}")
>>> print(f"Age advance: {result['cosinorage_advance']:.1f}")
>>> print(f"MESOR: {result['mesor']:.4f}")
>>> print(f"Amplitude: {result['amp1']:.4f}")
>>> print(f"Acrophase: {result['phi1']:.4f}")
```