# lasugden/arhmm-cycle-tracking architecture

> Architecture diagram of the GitHub repository lasugden/arhmm-cycle-tracking, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lasugden/arhmm-cycle-tracking
- Repository: https://github.com/lasugden/arhmm-cycle-tracking

## Overview

This is a hormone-cycle analysis pipeline: the organizer loads participant, cycle, and hormone exports, enriches and filters cycle data, trains or runs an HMM, and assembles cycle-level features for downstream analysis. Its HMM stages prepare hormone sequences, infer phases, and persist phase/log-probability outputs; separate modules support phase annotation, classification, and visual summaries. The README identifies the organizer as the entry point. Several organizer operations and downstream calls are in omitted excerpts, so only explicit calls or documented entry points are linked; dashed edges mark likely but unverified handoffs.

Main entry points: [`code/hormone_organizer.py`](https://github.com/lasugden/arhmm-cycle-tracking/blob/main/code/hormone_organizer.py) (Hormone organizer), [`code/run_HMM.py`](https://github.com/lasugden/arhmm-cycle-tracking/blob/main/code/run_HMM.py) (Cycle HMM runner), [`code/add_viterbi_phase.py`](https://github.com/lasugden/arhmm-cycle-tracking/blob/main/code/add_viterbi_phase.py) (Phase annotation), [`code/train_HMM.py`](https://github.com/lasugden/arhmm-cycle-tracking/blob/main/code/train_HMM.py) (HMM indexing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Data ingestion"]
  node_cycle_reader["Cycle reader<br/>[cycles.py]"]
  node_hormone_reader["Hormone reader<br/>[hormones.py]"]
  node_info_reader["Participant reader<br/>[info.py]"]
  node_cycle_export["Cycle export"]
  node_hormone_export["Hormone export"]
  node_info_export["Participant export"]
  node_mood_reader["Mood reader<br/>[mood.py]"]
  node_symptom_reader["Symptom reader<br/>[symptom.py]"]
end

subgraph group_prepare["Cycle preparation"]
  node_organizer["Hormone organizer"]
  node_pcos_label["PCOS labeling<br/>[add_pcos_label.py]"]
end

subgraph group_hmm["HMM inference"]
  node_indexing["HMM indexing<br/>[train_HMM.py]"]
  node_parameter_files["HMM parameters"]
  node_runner["Cycle HMM runner<br/>[run_HMM.py]"]
  node_interpolation["Sequence interpolation<br/>[interpolate.py]"]
  node_hmm_model["HMM model<br/>[hmm.py]"]
  node_phase_files["Phase outputs"]
end

subgraph group_analysis["Analysis outputs"]
  node_phase_annotation["Phase annotation"]
  node_alignment["Cycle alignment<br/>[alignment.py]"]
  node_missingness["Missingness extraction"]
  node_classifier["Group classifier<br/>[classify.py]"]
  node_plots["Plot generation<br/>[make_plots.py]"]
end

node_analyst(("Analyst"))

node_organizer -->|"loads cycles"| node_cycle_reader
node_organizer -->|"loads hormones"| node_hormone_reader
node_organizer -->|"loads participant data"| node_info_reader
node_cycle_reader -->|"reads CSV"| node_cycle_export
node_hormone_reader -->|"reads CSV"| node_hormone_export
node_info_reader -->|"reads CSV"| node_info_export
node_organizer -.->|"adds PCOS labels"| node_pcos_label
node_organizer -->|"adds indexing"| node_indexing
node_organizer -->|"runs all cycles"| node_runner
node_runner -->|"deduplicates and expands"| node_indexing
node_runner -->|"interpolates sequences"| node_interpolation
node_runner -.->|"infers phase paths"| node_hmm_model
node_indexing -->|"writes emissions"| node_parameter_files
node_hmm_model -->|"reads parameters"| node_parameter_files
node_runner -->|"writes phase results"| node_phase_files
node_organizer -->|"adds phase features"| node_phase_annotation
node_phase_annotation -->|"reads phase outputs"| node_phase_files
node_phase_annotation -.->|"computes alignments"| node_alignment
node_organizer -.->|"extracts missingness"| node_missingness
node_analyst -->|"starts workflow"| node_organizer
node_analyst -.->|"evaluates groups"| node_classifier
node_analyst -.->|"requests plots"| node_plots

click node_organizer "https://github.com/lasugden/arhmm-cycle-tracking/blob/main/code/hormone_organizer.py"
click node_cycle_reader "https://github.com/lasugden/arhmm-cycle-tracking/blob/main/code/readers/cycles.py"
click node_hormone_reader "https://github.com/lasugden/arhmm-cycle-tracking/blob/main/code/readers/hormones.py"
click node_info_reader "https://github.com/lasugden/arhmm-cycle-tracking/blob/main/code/readers/info.py"
click node_pcos_label "https://github.com/lasugden/arhmm-cycle-tracking/blob/main/code/add_pcos_label.py"
click node_indexing "https://github.com/lasugden/arhmm-cycle-tracking/blob/main/code/train_HMM.py"
click node_runner "https://github.com/lasugden/arhmm-cycle-tracking/blob/main/code/run_HMM.py"
click node_interpolation "https://github.com/lasugden/arhmm-cycle-tracking/blob/main/code/interpolate.py"
click node_hmm_model "https://github.com/lasugden/arhmm-cycle-tracking/blob/main/code/hmm.py"
click node_phase_annotation "https://github.com/lasugden/arhmm-cycle-tracking/blob/main/code/add_viterbi_phase.py"
click node_alignment "https://github.com/lasugden/arhmm-cycle-tracking/blob/main/code/alignment.py"
click node_missingness "https://github.com/lasugden/arhmm-cycle-tracking/blob/main/code/extract_missingness.py"
click node_classifier "https://github.com/lasugden/arhmm-cycle-tracking/blob/main/code/classify.py"
click node_plots "https://github.com/lasugden/arhmm-cycle-tracking/blob/main/code/make_plots.py"
click node_mood_reader "https://github.com/lasugden/arhmm-cycle-tracking/blob/main/code/readers/mood.py"
click node_symptom_reader "https://github.com/lasugden/arhmm-cycle-tracking/blob/main/code/readers/symptom.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cycle_reader,node_hormone_reader,node_info_reader,node_cycle_export,node_hormone_export,node_info_export,node_mood_reader,node_symptom_reader toneBlue
class node_organizer,node_pcos_label toneAmber
class node_indexing,node_parameter_files,node_runner,node_interpolation,node_hmm_model,node_phase_files toneMint
class node_phase_annotation,node_alignment,node_missingness,node_classifier,node_plots toneRose
class node_analyst toneIndigo
```

## Components

### Data ingestion

- [Cycle reader](https://github.com/lasugden/arhmm-cycle-tracking/blob/main/code/readers/cycles.py): `code/readers/cycles.py`
- [Hormone reader](https://github.com/lasugden/arhmm-cycle-tracking/blob/main/code/readers/hormones.py): `code/readers/hormones.py`
- [Participant reader](https://github.com/lasugden/arhmm-cycle-tracking/blob/main/code/readers/info.py): `code/readers/info.py`
- **Cycle export**
- **Hormone export**
- **Participant export**
- [Mood reader](https://github.com/lasugden/arhmm-cycle-tracking/blob/main/code/readers/mood.py): `code/readers/mood.py`
- [Symptom reader](https://github.com/lasugden/arhmm-cycle-tracking/blob/main/code/readers/symptom.py): `code/readers/symptom.py`

### Cycle preparation

- [Hormone organizer](https://github.com/lasugden/arhmm-cycle-tracking/blob/main/code/hormone_organizer.py): `code/hormone_organizer.py`
- [PCOS labeling](https://github.com/lasugden/arhmm-cycle-tracking/blob/main/code/add_pcos_label.py): `code/add_pcos_label.py`

### HMM inference

- [HMM indexing](https://github.com/lasugden/arhmm-cycle-tracking/blob/main/code/train_HMM.py): `code/train_HMM.py`
- **HMM parameters**
- [Cycle HMM runner](https://github.com/lasugden/arhmm-cycle-tracking/blob/main/code/run_HMM.py): `code/run_HMM.py`
- [Sequence interpolation](https://github.com/lasugden/arhmm-cycle-tracking/blob/main/code/interpolate.py): `code/interpolate.py`
- [HMM model](https://github.com/lasugden/arhmm-cycle-tracking/blob/main/code/hmm.py): `code/hmm.py`
- **Phase outputs**

### Analysis outputs

- [Phase annotation](https://github.com/lasugden/arhmm-cycle-tracking/blob/main/code/add_viterbi_phase.py): `code/add_viterbi_phase.py`
- [Cycle alignment](https://github.com/lasugden/arhmm-cycle-tracking/blob/main/code/alignment.py): `code/alignment.py`
- [Missingness extraction](https://github.com/lasugden/arhmm-cycle-tracking/blob/main/code/extract_missingness.py): `code/extract_missingness.py`
- [Group classifier](https://github.com/lasugden/arhmm-cycle-tracking/blob/main/code/classify.py): `code/classify.py`
- [Plot generation](https://github.com/lasugden/arhmm-cycle-tracking/blob/main/code/make_plots.py): `code/make_plots.py`

### Other components

- **Analyst**

## Connections

- Hormone organizer → Cycle reader: loads cycles (evidence: `code/hormone_organizer.py`)
- Hormone organizer → Hormone reader: loads hormones (evidence: `code/hormone_organizer.py`)
- Hormone organizer → Participant reader: loads participant data (evidence: `code/hormone_organizer.py`)
- Cycle reader → Cycle export: reads CSV (evidence: `code/readers/cycles.py`)
- Hormone reader → Hormone export: reads CSV (evidence: `code/readers/hormones.py`)
- Participant reader → Participant export: reads CSV (evidence: `code/readers/info.py`)
- Hormone organizer → PCOS labeling: adds PCOS labels
- Hormone organizer → HMM indexing: adds indexing (evidence: `code/hormone_organizer.py`)
- Hormone organizer → Cycle HMM runner: runs all cycles (evidence: `code/hormone_organizer.py`)
- Cycle HMM runner → HMM indexing: deduplicates and expands (evidence: `code/run_HMM.py`)
- Cycle HMM runner → Sequence interpolation: interpolates sequences (evidence: `code/run_HMM.py`)
- Cycle HMM runner → HMM model: infers phase paths
- HMM indexing → HMM parameters: writes emissions (evidence: `code/train_HMM.py`)
- HMM model → HMM parameters: reads parameters (evidence: `code/hmm.py`)
- Cycle HMM runner → Phase outputs: writes phase results (evidence: `code/run_HMM.py`)
- Hormone organizer → Phase annotation: adds phase features (evidence: `code/hormone_organizer.py`)
- Phase annotation → Phase outputs: reads phase outputs (evidence: `code/add_viterbi_phase.py`)
- Phase annotation → Cycle alignment: computes alignments
- Hormone organizer → Missingness extraction: extracts missingness
- Analyst → Hormone organizer: starts workflow (evidence: `README.md`)
- Analyst → Group classifier: evaluates groups
- Analyst → Plot generation: requests plots