Skip to content

Latest commit

 

History

History
256 lines (184 loc) · 10.8 KB

README.md

File metadata and controls

256 lines (184 loc) · 10.8 KB

Cycle Stability Index (CSI)

Status Data License Python Org

A composite index for quantifying menstrual-cycle instability across 8 clinical domains, weighted by an 8-expert AHP panel.

Organization: The MidTech
Repository: https://github.com/The-MidTech/CSI

Authors

Name Role
Fatemeh Afshari Midwife · project design · clinical content & evaluation · data review · software development
Hanieh Khaleoghli MSc Artificial Intelligence · software development · data evaluation & quality checks

Built jointly under The MidTech.

⚠️ Important
This is a v0.3.0 engineering prototype.
It has been tested only on synthetic (simulated) data.
It is not a clinically validated instrument and must not be used for diagnosis or treatment decisions.
Real-world pilot validation is planned after ethics / IRB approval.


What CSI measures

CSI does not measure a single symptom. It quantifies how much a person’s cycle varies / destabilizes across eight domains:

Domain Weight What it captures Source instrument
Cycle Regularity 29.4 % Variability in cycle length FIGO 2018 criteria
Bleeding 27.4 % Heaviness & duration of bleeding PBAC (Higham et al. 1990)
Pain 11.1 % Dysmenorrhea intensity & impact NRS (validated cut-offs)
PMS 8.9 % Premenstrual symptom severity PSST (Steiner et al. 2003)
Functioning 9.0 % Impact of the cycle on daily activities WSAS (Mundt et al. 2002), adapted
Mood 4.9 % Cycle-related negative mood DRSP mood subscale (Endicott 2006)
Energy 4.7 % Cycle-related fatigue FSS (Krupp et al. 1989)
Sleep 4.6 % Cycle-related sleep disruption PSQI (Buysse et al. 1989)

CSI range

Score Category (Persian) Meaning
CSI ≥ 0.7 سیکل پایدار Stable
0.3 ≤ CSI < 0.7 سیکل متوسط Moderate
CSI < 0.3 سیکل ناپایدار Unstable

How the weights were derived

The eight domain weights are not arbitrary. They come from a structured AHP (Analytic Hierarchy Process) panel:

  1. Eight experts (obstetrics/gynaecology, midwifery, psychiatry) each completed a 28-item pairwise-comparison questionnaire (Saaty 1–9 scale).
  2. Each expert’s matrix was converted to a priority vector via the geometric-mean method; a Consistency Ratio (CR) was computed per expert.
  3. One expert’s initial response had CR = 0.122 (above the 0.10 threshold). A circular contradiction was identified and corrected (CR dropped to 0.078).
  4. Final weights = arithmetic mean of all eight priority vectors. Overall mean CR = 0.071 (acceptable).

Scoring architecture

raw item  →  normalized item (0–1)  →  domain subscale (0–1)  →  CSI (0–1)
  • Normalization: each raw item has a defined clinical min/max, linearly mapped to 0–1. Direction is always “higher = more unstable”.
  • Subscale: simple average of the domain’s normalized items (equal item-level weighting in this version).
  • CSI: 1 − Σ (domain_weight × domain_subscale)

Full item list and ranges → src/csi_engine.py (DOMAIN_ITEMS).
Evidence sources → REFERENCES.md.


Synthetic data (v0.3.0)

The file data/synthetic_respondents.csv contains 200 simulated respondents.

Marginal calibration (general-population targets)

Variable Distribution used Typical result in this file
PBAC_score Gamma (k≈2, scale by profile) ~15–20 % ≥ 100 (HMB threshold)
PSQI_global_score Truncated Normal ~35–45 % > 5 (poor sleep)
WSAS_total_score Truncated Normal ~10–15 % > 20 (severe impairment)
cycle_length_sd Log-normal never exactly 0 (Apple Women’s Health Study)
Dysmenorrhea Truncated Normal ~90–97 % report some pain

Inter-domain structure (v0.3.0 improvement)

Earlier versions used a single global severity factor (stable / mixed / unstable) that shifted all domains together. That produced unrealistically high inter-subscale correlations (mean |r| ≈ 0.54).

v0.3.0 uses eight latent profiles, including domain-dominant and discordant patterns:

Profile What it emphasises
stable Most domains low
mixed_mild Mild elevation across several domains
pain_dominant High pain; sleep/mood milder
bleed_dominant High PBAC/duration; mood relatively spared
pms_mood_dominant High PSST & DRSP; cycle relatively regular
cycle_irregular High cycle-length SD; other domains milder
sleep_energy High PSQI & FSS; bleeding/pain milder
globally_unstable Several high-weight domains elevated (for CSI < 0.3)

Typical diagnostics on the shipped file:

  • Mean |r| between subscales ≈ 0.35–0.40 (was ≈ 0.54)
  • Residual |r| within profile ≈ 0.06
  • Discordant combinations present (e.g. severe pain + good sleep, heavy bleed + mild mood)
  • ~12–20 respondents with CSI < 0.3 so the full score range is still testable

Data-leakage note: CSI, the eight subscales, and category are derived from the raw items. Do not use them as independent features alongside each other in downstream models without a clear causal design.


Repository structure

csi/
├── src/
│   ├── __init__.py
│   ├── csi_engine.py              # core scoring logic
│   ├── generate_synthetic_data.py # builds the 200-row synthetic dataset
│   └── sensitivity_analysis.py    # Monte-Carlo robustness check
├── data/
│   └── synthetic_respondents.csv  # simulated data only — NOT real patients
├── docs/
│   └── CSI_questionnaire_fa.docx  # Persian self-report questionnaire (paraphrased)
├── tests/
│   └── test_csi_engine.py
├── REFERENCES.md
├── LICENSE
├── requirements.txt
└── README.md

Installation

git clone https://github.com/The-MidTech/CSI.git
cd csi
python -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate
pip install -r requirements.txt

Quick usage

from src.csi_engine import compute_csi, classify_csi

raw = {
    "cycle_length_sd": 3,
    "PBAC_score": 80,
    "bleeding_duration_days": 6,
    "dysmenorrhea_intensity_NRS": 5,
    "pain_days_per_cycle": 3,
    "analgesic_use_pattern": 1,
    "PSST_total_score": 20,
    "DRSP_negative_mood_score": 22,
    "PSQI_global_score": 7,
    "FSS_total_score": 30,
    "WSAS_total_score": 14,
}

result = compute_csi(raw)
print(f"CSI = {result['CSI']:.3f}")
print(f"Category = {classify_csi(result['CSI'])}")
print(result["data_quality_warnings"])

Run the built-in smoke test:

python -m src.csi_engine

Reproducing the synthetic dataset & sensitivity analysis

# regenerate the 200 synthetic respondents
python src/generate_synthetic_data.py

# Monte-Carlo weight-perturbation test (1000 iterations)
python src/sensitivity_analysis.py

Running the tests

pip install pytest
pytest tests/ -v

Limitations (v0.3.0)

  • Synthetic data only. No real patient data has been collected.
  • Equal item weighting inside each domain.
  • Simplified / paraphrased versions of the source instruments (shortened PSQI, adapted WSAS, Persian paraphrases of PSST & DRSP). Author-approved, linguistically validated translations are required before formal data collection.
  • CSI assumes an active cycle. Zero bleeding days triggers an explicit warning (flag_data_quality) because amenorrhoea is outside the design scope.
  • No covariate adjustment (contraceptives, stress, chronic conditions, age) — these should be collected alongside CSI for later analysis.
  • No clinical validation yet. Content validity is grounded in named instruments; construct validity, reliability and convergent validity still require a real pilot (n ≥ 250) and ethics approval.

See REFERENCES.md for the exact source of every item and the permissions that must be obtained before any formal study.


Planned next phase (after ethics approval)

  1. IRB / ethics approval + real pilot data collection (n ≥ 250)
  2. Reliability testing (internal consistency, test–retest)
  3. Construct validity (exploratory factor analysis)
  4. Convergent validity against the original validated instruments
  5. Covariate-adjusted analyses

Authors & citation

Fatemeh Afshari — midwife; project design; clinical content and evaluation; data review; software development.
Hanieh Khaleoghli — MSc Artificial Intelligence; software development; data evaluation and quality checks.

If you use this code or the CSI concept in academic work, please cite:

Afshari, F., & Khaleoghli, H. (2026). Cycle Stability Index (CSI) — v0.3.0 [Computer software].
The MidTech. https://github.com/The-MidTech/CSI

and the original instrument papers listed in REFERENCES.md.

See also AUTHORS.md.


License

MIT License — see LICENSE.

Note on third-party instruments: PBAC, PSST, DRSP, PSQI, FSS and WSAS remain the intellectual property of their original authors. Before using the questionnaire in an ethics-approved study you must obtain any required permissions / translations from those authors or publishers.