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
--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.

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 (for example asthma or emphysema hypotheses) are set in the web app. A run made with one is marked as a scenario in result.json and on every page of the report.
• Lobectomy and reinflation runs are prepared in the web app (see Reinflation); download-spirometry saves them like any other run.