Usage

Command-line interface

Installing the package registers a single tadpose command that dispatches to one subcommand per pipeline stage:

tadpose --help                 # list the available stages
tadpose config                 # show the resolved active profile/data root
tadpose config --export hpc    # emit TADPOSE_* shell vars for the hpc profile
tadpose <stage> --help         # options for an individual stage

Available stages include config, assign-clusters, label, markov-chain, markov-chain-groups, cluster-meta and metrics. Each stage derives its default input and output paths from tadpose.config.data_root(), so a correctly filled local_paths.json (see Installation) is all that is required to run a stage on a new machine.

Choosing the number of clusters

The metrics stage builds an internal cluster-validation summary over a k sweep — Calinski–Harabasz, within-cluster inertia with a Kneedle elbow, and (optionally) a stratified silhouette that fairly represents rare seizure motifs — and writes a CSV (and optional figure):

tadpose metrics --meta-dir <clustering_results> --data-file <zscored.npy> \
    --output-csv selection_summary.csv --silhouette --plot selection

See tadpose.analysis.internal_metrics for the underlying functions (compute_silhouette_stratified, compute_inertia, locate_elbow_kneedle, selection_summary).

Using the library

The core feature functions are pure and importable. For example, decomposing centre-of-mass motion into body-frame velocity components:

import numpy as np
from tadpose import feature_extraction as fe

com = np.array([[0.0, 0.0], [2.0, 0.0], [4.0, 0.0]])  # (N, 2) pixels
yaw = fe.compute_yaw(frons_xy, tail_base_xy)           # body orientation
vel = fe.compute_velocity(com, yaw, fps=50.0, px_diameter=340.0)
# -> {"thrust": ..., "slip": ..., "yaw_speed": ...}

Figures are written through tadpose.viz_constants.save_figure(), which exports an editable-text SVG and a PNG (and an optional CSV data companion) using the Wong (2011) colourblind-safe palette.

High-performance computing

Pose estimation and clustering at scale are designed for a SLURM cluster. The submit scripts under slurm/ source slurm/load_paths.sh so that the interpreter, code root, data root and account come from the same local_paths.json used by the Python package, keeping every #SBATCH line machine-agnostic.