COVING INDEX: Self-contained Flow–Volume Analysis

Project Description

This repository provides a minimal, self-contained implementation for calculating the COVING INDEX from spirometry flow–volume data. The COVING INDEX is a dimensionless metric that quantifies the "bowing" of the expiratory flow–volume curve, supporting research and reproducibility in respiratory science. This code is intended for scientific and academic use, and is suitable for publication, reference, and demonstration purposes.

Purpose and Scope

The project enables researchers to:

• Compute the COVING INDEX from raw or pre-processed spirometry data
• Understand and visualize the COVING INDEX calculation process

The code is provided as-is for reference and is not intended for clinical or production use.

Software Requirements

• Python 3.8 or higher
• Supported platforms: Windows, macOS, Linux
• Dependencies: pandas, numpy, scipy, matplotlib, seaborn

Install dependencies (PowerShell):

pip install pandas numpy scipy matplotlib seaborn

Version

Current release: 0.1.0

---

What this does

• Downloads a public spirometry dataset automatically (if missing).
• Tidies the data and resamples curves to uniform time steps.
• Computes the COVING INDEX per test session using coving_index.py.
• Shows a compact preview of results; saving artifacts is optional.
• Accepts flow–volume data including tidal breathing and full inspiration/expiration loops.

How the COVING INDEX is computed

At a high level, the COVING INDEX measures the "bowing" of the expiratory flow–volume curve relative to a straight reference line. Steps:

1. Identify the forced expiration segment: find peak expiratory flow (PEF) and select the continuous positive-flow portion from PEF to the end of expiration.
2. Build a straight reference: draw a straight line in flow–volume space between the start and end points of that expiration segment (linear interpolation of flow vs. volume).
3. Compute areas: integrate the reference line (linear flow) and the actual measured flow over volume using the trapezoidal rule.
4. COVING AREA = Area(reference) − Area(actual). COVING INDEX = COVING AREA / Area(reference).

This produces a dimensionless index in [0, 1] (when valid), where higher values indicate greater bowing below the straight-line reference.

Visual representation of the COVING INDEX computation showing the reference line and COVING AREA.

Files

• Coving_Index_calculator.ipynb — the main notebook.
• coving_index.py — minimal self-contained COVING INDEX implementation used by the notebook.

Data structure and session identification

The code expects your data to have these columns:

• patient_id: identifies the individual patient/subject
• year: represents the visit or timepoint (e.g., baseline, year 1, year 2)
• trial_id: distinguishes multiple test attempts within the same visit
• time: time in seconds (uniformly sampled)
• flow: airflow in L/s
• volume: lung volume in liters

A unique spirometry session is identified by the combination of (patient_id, year, trial_id). Each session contains multiple time-series measurements of flow and volume from a single test.

How to run and use

1. Open Coving_Index_calculator.ipynb in VS Code or Jupyter.
2. Run all cells. If the data file (spirotidydatafinal.txt) is not present, it will be downloaded automatically from the figshare repository.
3. The notebook will:
   • Load and tidy the spirometry flow–volume data
   • Resample to uniform time steps (dt=0.01 s)
   • Compute COVING INDEX values per session
   • Print a compact preview of the results

Data source

The notebook automatically downloads a sample dataset from:

• Dataset: Raw Spirometry Dataset (Inspiratory and Expiratory)
• Citation: Belman MJ, Amin S, D'Souza S, Khan Y, Alfaras M, Bailey K, Jayachandran R, Mohanan S, Hiremath A, Kottam A, Chandrasekaran B. A Spirometry Dataset (2022). figshare. Dataset. https://doi.org/10.6084/m9.figshare.19196543.v2
• Direct download: https://figshare.com/ndownloader/files/34418276
• Description: The dataset contains flow–volume measurements including tidal breathing, full inspiratory, and expiratory maneuvers from healthy individuals.

Notes

• The notebook is designed for scientists and researchers; code comments explain each step.
• All required code and documentation are included in this folder—no external dependencies beyond standard Python packages.

---

---

Acknowledgments

Developed by: AstraZeneca Data Science and Advanced Analytics Team in R&D Biopharma.