Virtual Spirometry

The client can run the same virtual spirometry as the web app’s Virtual Spirometry panel (see Spirometry Setup) and save its results on your computer: the values FEV1, FVC, PEF and FEV1/FVC, the curves, and the PDF report. Before you start, sign in; patient and series are chosen as in Segmentation and STL Export.

Run a simulation

climed-client virtual-spirometry --patient "John Doe" --out ./john_doe_spiro

The simulation runs on the server and is stored with the patient, as from the web app. It usually takes 3 to 5 minutes; when the lobes or the airways are not segmented yet, the server segments them first and it takes longer. The progress is shown as it goes (“Lung segmentation”, “Running simulation”, …).

At the end it prints one line, <run> <FEV1 L> <FVC L> <PEF L/s> [folder]:

20261014_222804_forcedExpiration 3.483 4.539 7.467 ./john_doe_spiro/20261014_222804_forcedExpiration

Option	Meaning
--age, --height, --weight, --bmi, --sex	The patient’s data (years, cm, kg, kg/m², male or female). Read from the patient’s record when left out, as the web panel does; a value you give replaces the one in the record
--mode	forced_expiration (default) or oscillatory
--fibrosis, --asthma, --emphysema	Run an exploratory scenario instead of the patient’s baseline, at mild, moderate or severe (see Explore a scenario)
--out	Also save the results in this folder (see below)
--no-pdf	Do not write the PDF report
--timeout	How long to wait, in seconds (default 3600)

The breathing effort of the simulation is computed from age, height, weight and sex. When some are missing the client says which: the simulation still runs, but with an effort that does not reflect this patient. Fill them in the patient record, or pass them on the command line.

If you stop waiting (Ctrl-C or --timeout), the simulation goes on on the server: fetch the results later with download-spirometry.

Module and credits. Virtual spirometry needs the Respirology module on your account; without it the client stops before sending anything. Where your installation uses credits, the GPU time of the run (the segmentation of lobes and airways included, when the server has to do it) is charged when it succeeds; a failed run costs nothing. If your credits do not cover a run, the server refuses it and the client says so (not enough credits, with the amount needed and available): nothing is started.

Explore a scenario

As in the web panel (see Spirometry Setup), you can ask a “what if” question about the same lungs: what would this patient’s spirometry look like with fibrosis, asthma or emphysema? Give the disease and its severity, mild, moderate or severe:

climed-client virtual-spirometry --patient "John Doe" --emphysema moderate --out ./john_doe_spiro

Option	What changes in the simulation
--fibrosis	A stiffer lung: the compliance goes from 80 ml/cmH₂O (healthy) to 60, 40 or 25
--asthma	Narrower airways: a higher airway resistance limits the airflow
--emphysema	Less elastic recoil: the airways collapse earlier and limit the airflow

The diseases combine, as in the panel: give two or three options in the same command. Two combinations have a clinical name, and the client prints it:

# asthma + emphysema: asthma-COPD overlap
climed-client virtual-spirometry --patient "John Doe" --asthma mild --emphysema severe
# fibrosis + emphysema: combined pulmonary fibrosis and emphysema (CPFE)
climed-client virtual-spirometry --patient "John Doe" --fibrosis moderate --emphysema mild

Fibrosis is always available. Asthma and emphysema need tables that the server must have: the client asks the server first, and if it cannot run what you asked it stops before starting anything, so nothing is charged, and it lists what is available (this server cannot run …; it offers: …).

The client marks the run as a scenario everywhere:

  SCENARIO fibrosis_moderate+emphysema_mild (combined pulmonary fibrosis and emphysema, CPFE)
  Exploratory scenario, not a measurement of this patient. Severity steps span the clinical scale but are not calibrated on patients.
  job fdd39f3d-… started; it usually takes 3-5 minutes, more if it must segment first
  …
  SCENARIO fibrosis_moderate+emphysema_mild: a hypothesis, not this patient's measurement
20261101_142203_forcedExpiration__scenario-fibrosis+emphysema_mild 1.542 2.580 2.684 ./john_doe_spiro/20261101_142203_forcedExpiration__scenario-fibrosis_emphysema_mild

The run name says the scenario (__scenario-…); only the severity of fibrosis is missing there, and the messages, result.json and the report carry it.

• in the messages, as above;
• with --json, in the scenario field (null for the patient’s baseline);
• on every page of report.pdf (SCENARIO: …, simulated hypothesis, NOT this patient's measurement), and in result.json (scenario_requested).

⚠️ A scenario is a hypothesis, not a measurement. The severity steps span the clinical scale but are not calibrated on patients. Read a scenario run next to the patient’s own baseline (the same command without the scenario options), never on its own.

Save a fibrosis run with --out when you run it. The server stores asthma and emphysema runs with the scenario in their name, so download-spirometry recognises them later. A run with fibrosis alone carries no such mark on the server, the same as in the web app’s Data tree. Only the copy saved by virtual-spirometry --out is marked. Downloaded later, it looks like a baseline run, so keep its run name.

Scenarios need climed-client 0.5.0 or later: climed-client --version tells you yours.

Download the results

Every run is kept with the patient. To save them on your computer:

climed-client download-spirometry --patient "John Doe" --out ./john_doe_spiro           # the latest run
climed-client download-spirometry --patient "John Doe" --out ./john_doe_spiro --all     # every run
climed-client download-spirometry --patient "John Doe" --out ./john_doe_spiro --run 20261014_222804_forcedExpiration

Each run gets its own folder:

john_doe_spiro/
└── 20261014_222804_forcedExpiration/
    ├── values.csv
    ├── curve.csv
    ├── report.pdf
    └── result.json

File	Contents
values.csv	One row for the whole lungs (total), each lung and each lobe: FEV1_L, FVC_L, PEF_L_s, FEV1_FVC_pct
curve.csv	The forced expiration, one row per time step: time_s, volume_L (exhaled volume), flow_L_s. Volume against flow is the flow-volume curve, time against volume the volume-time curve
report.pdf	The report: patient, series and run, the values table, the two curves (FEV1 marked at 1 second) and the figures the server rendered for the run (lung contraction, lobar emptying, regional ventilation, airway airflow)
result.json	Everything the server returned for the run, for your own processing

values.csv (the values keep the full precision of the simulation; round them as you need):

scope,FEV1_L,FVC_L,PEF_L_s,FEV1_FVC_pct
total,3.1954795497221005,4.382061942885201,6.2801573845994145,72.92
left_lung,1.3794818656504997,1.9915259000285996,1.4168381568251343,69.27
right_lung,1.8159976840716001,2.3905360428566,1.728090982557595,75.97
lung_upper_lobe_left,0.6556153315658,0.9409993141986999,1.232252478959071,69.67
…

The PDF report needs one extra component on your computer. Install the client with it:

pip install "./climed_client-X.Y.Z-py3-none-any.whl[pdf]"

Without it, values.csv, curve.csv and result.json are written as usual and the client tells you how to add the PDF. The report has the same content as the one you export from the web app; the layout is its own.

Good to know

• Simulated, not measured. These are values computed from the CT geometry, not a measurement of the patient: there are no predicted values and no % of predicted. Every page of the report says so.
• Scenarios (fibrosis, asthma, emphysema, alone or combined) run from the client with --fibrosis, --asthma and --emphysema (see Explore a scenario) or from the web app. A scenario run is marked in the messages, in result.json and on every page of the report. The one exception is a fibrosis-alone run that is downloaded later.
• Lobectomy and reinflation runs are prepared in the web app (see Reinflation); download-spirometry saves them like any other run.