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
| 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.
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 |
The eight domain weights are not arbitrary. They come from a structured AHP (Analytic Hierarchy Process) panel:
- Eight experts (obstetrics/gynaecology, midwifery, psychiatry) each completed a 28-item pairwise-comparison questionnaire (Saaty 1–9 scale).
- Each expert’s matrix was converted to a priority vector via the geometric-mean method; a Consistency Ratio (CR) was computed per expert.
- 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).
- Final weights = arithmetic mean of all eight priority vectors. Overall mean CR = 0.071 (acceptable).
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.
The file data/synthetic_respondents.csv contains 200 simulated respondents.
| 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 |
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, andcategoryare derived from the raw items. Do not use them as independent features alongside each other in downstream models without a clear causal design.
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
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.txtfrom 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# regenerate the 200 synthetic respondents
python src/generate_synthetic_data.py
# Monte-Carlo weight-perturbation test (1000 iterations)
python src/sensitivity_analysis.pypip install pytest
pytest tests/ -v- 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.
- IRB / ethics approval + real pilot data collection (n ≥ 250)
- Reliability testing (internal consistency, test–retest)
- Construct validity (exploratory factor analysis)
- Convergent validity against the original validated instruments
- Covariate-adjusted analyses
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.
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.