thermophysio

A Python library for extracting, analysing, and cross-correlating skin temperature time-series from FLIR thermal infrared camera recordings of human participants during psychophysiology experiments.

Overview

The pipeline extracts temperature signals from anatomically defined regions of interest (ROIs) on the face, scalp, and neck, then asks: does the difference in a thermal feature between two regions correlate with task activation?

Three camera configurations are supported:

Installation

pip install thermophysio

MediaPipe and Ultralytics (YOLOv8) are installed as dependencies. YOLOv8 weights (yolov8n-pose.pt) are downloaded automatically on first use.

For development / editable install from source:

git clone https://github.com/RauwP/thermophysio
cd thermophysio
pip install -e .

Experiment Types

Workflow

Step 1 — Extraction (interactive, per session)

from thermophysio import extract_back, extract_frontal, extract_profile

# Back-of-head camera (Faces experiment)
extract_back(
    img_dir="Experiments/Exp01-Faces",
    out_dir="Calc_Experiments/Exp01-Faces",
    model="yolov8n-pose.pt"
)

# Frontal camera (GoNoGo, Words, CORSI)
extract_frontal(
    img_dir="Experiments/Exp06-GoNoGo",
    out_dir="Calc_Experiments/Exp06-GoNoGo"
)

# Dual side-profile (LogicalVsIllogical)
extract_profile(
    dir_a="Experiments/Exp22-LogicalVsIllogical/CamA",
    dir_b="Experiments/Exp22-LogicalVsIllogical/CamB",
    out_dir="Calc_Experiments/Exp22-LogicalVsIllogical",
    model="yolov8n-pose.pt"
)

Each call opens a GUI for entering block timings, then processes all frames automatically. Outputs land in:

Calc_Experiments/Exp01-Faces/
  raw/                      session_meta.json + overlays/ + pixels/
  stats.csv                 10 features × all ROIs × all timepoints
  stats_resampled.csv       uniformly resampled at dt=5 s
  analysis/
    ccf_table.csv           all (feature × pair) CCF results, ranked
    top10_leaderboard.png   top-10 bar chart with Bartlett CI
    top10_ccf_grid.png      5×2 grid of top-10 full CCF curves
    plots/                  individual CCF plots + per-feature grids

If extraction was done separately into Processed_Experiments/, run only the analysis pipeline:

from thermophysio._pipeline import run_pipeline

run_pipeline(
    raw_dir="Processed_Experiments/Exp01-Faces",
    out_dir="Calc_Experiments/Exp01-Faces"
)

Step 2 — Meta-Analysis (post-hoc, across runs of same type)

python -m thermophysio.FLIR_Meta_Analysis \
    Calc_Experiments/Exp01-Faces/analysis/ccf_table.csv \
    Calc_Experiments/Exp02-Faces/analysis/ccf_table.csv \
    Calc_Experiments/Exp03-Faces/analysis/ccf_table.csv \
    Calc_Experiments/Exp04-Faces/analysis/ccf_table.csv \
    Calc_Experiments/Exp05-Faces/analysis/ccf_table.csv \
    Calc_Experiments/Exp08-Faces/analysis/ccf_table.csv \
    --out Calc_Experiments/Meta_Faces \
    --label "Faces" \
    --min-runs 2

Outputs: leaderboard PNG, table PNG, full AI-readable markdown report.

Repository Structure

thermophysio/                 Installable package
  __init__.py                 Public API: extract_frontal / extract_back / extract_profile
  _pipeline.py                Orchestrator: build_csv → resample → analyse → summarise
  Back_FLIR_Extractor.py      YOLOv8 back-of-head pipeline
  Frontal_FLIR_Extractor.py   MediaPipe frontal pipeline
  Dual_FLIR_Extractor.py      YOLOv8 dual side-profile pipeline
  FLIR_Stats_to_CSV.py        NPZ → 10-feature stats CSV
  FLIR_TimeSeries.py          Irregular → uniform time resampling
  FLIR_CrossROI_Analysis.py   Bartlett-corrected CCF analysis + plots
  FLIR_Top_Correlations.py    Top-N leaderboard and CCF grid (per session)
  FLIR_Meta_Analysis.py       Fisher z meta-analysis across runs
  FLIR_Delta_Analysis.py      Pairwise Pearson delta analysis (alternative)
  shared_utils.py             Feature computation + CCF math
  mesh_defs.json              ROI polygon definitions (all 3 camera types)
  mesh_loader.py              JSON loader with GitHub download + local cache
  editors/
    back_mesh_editor.py       GUI editor for back-of-head ROI mesh
    frontal_mesh_editor.py    GUI editor for frontal ROI mesh
    profile_mesh_editor.py    GUI editor for dual-profile ROI mesh (J = export)

docs/
  assets/                     Representative overlays + meta-analysis figures
  REPORT.md                   Full technical report with math and results

Features Extracted per ROI

npixels (ROI size) is computed but excluded from correlation analysis.

Analysis Parameters

Dependencies

• numpy, scipy, matplotlib
• opencv-python, Pillow
• mediapipe (frontal extraction)
• ultralytics (YOLOv8, back/dual extraction)
• flyr (FLIR radiometric JPEG parsing)

Data Availability

Raw recordings, extracted pixel data, and analysis outputs are archived on Zenodo:

DOI: 10.5281/zenodo.19700602

The deposit contains three archives:

• Experiments.zip — raw FLIR radiometric JPEGs, one folder per session
• Processed_Experiments.zip — extracted pixel arrays (.npz), session metadata, and ROI overlay images
• Calc_Experiments.zip — per-session statistics CSVs, resampled time-series, CCF tables, and plots

See Also

docs/REPORT.md — full technical report covering coordinate geometry, feature math, statistical methods, and per-experiment results with figures.