---

name: unsupervised-methods description: "Author and run rPPG-Toolbox unsupervised_method configurations with POS, CHROM, ICA, GREEN, LGI, PBV, or OMIT, then diagnose signal, shape, sampling-rate, and evaluation-window failures." disable-model-invocation: true metadata: { disco-role: operating } license: NOASSERTION

Unsupervised rPPG methods

Use this skill when the toolbox must extract a blood-volume-pulse (BVP) signal from face-video color data without a trained neural model. This is an inference workflow: it selects one or more supported algorithms, obtains preprocessed clips through the dataset loader, computes a BVP, and evaluates heart rate against the loader's label signal. It does not train a model or replace dataset/cache preparation.

Fast route

1. Follow data preparation to create or reuse a valid cached clip/file-list set. Do not hand-build loader batches unless debugging the algorithm boundary.
2. Set TOOLBOX_MODE: "unsupervised_method", a non-empty UNSUPERVISED.METHOD list, a supported dataset, and the actual video sampling rate (UNSUPERVISED.DATA.FS). Use DATA_FORMAT: NDHWC.
3. Start with DATA_TYPE: ['Raw'], a label representation appropriate for the dataset, USE_PSUEDO_PPG_LABEL: False, and a clip long enough for the selected method and evaluation filter. See workflows.
4. Select INFERENCE.EVALUATION_METHOD: "FFT" or the exact string "peak detection"; choose only supported metrics. Use the smoke script before spending time on a dataset run: python scripts/unsupervised_smoke.py --help.
5. Run one method first. Add methods only after the first BVP and evaluation window are valid; dispatch runs the complete unsupervised dataloader once per method in list order.
6. If no windows reach evaluation, inspect shape, frame count, FS, label length, and the failure matrix in troubleshooting. For plots/formulas, follow evaluation and visualization.

Contract at the algorithm boundary

The loader returns a batched tensor. For the supported NDHWC convention, an individual item is D x H x W x C (frames/depth, height, width, channels). The predictor converts it to an array and passes data[..., :3] to the chosen method. Therefore the method input is RGB frames shaped (frames, height, width, 3), with the first three channels being the RGB video. Do not pass a label, a batch dimension, CHW data, or a time-major three-channel array.

DATA_TYPE controls video preprocessing, not the evaluation algorithm. Raw keeps frames; DiffNormalized computes frame differences and normalizes them; Standardized z-scores the video. Multiple entries are concatenated along the channel axis, but this predictor intentionally takes only the first three channels. For reliable traditional methods, use ['Raw']; if another type is needed for a controlled experiment, verify that its first three channels are still the intended RGB signal.

LABEL_TYPE controls only the label loaded for comparison (Raw, DiffNormalized, or Standardized). It is not passed to POS/CHROM/ICA/GREEN/ LGI/PBV/OMIT. Unsupervised mode rejects pseudo-PPG labels, so keep USE_PSUEDO_PPG_LABEL false. Labels and BVP must cover the same time interval; preprocessing and chunking should preserve that alignment.

Method selection

The exact accepted names and dispatch arguments are:

UNSUPERVISED.METHOD	Dispatch	FS passed to method	Practical choice
POS	POS_WANG(frames, fs)	yes	RGB projection with rolling 1.6-second windows
CHROM	CHROME_DEHAAN(frames, FS)	yes	chrominance projection with 1.6-second windows
ICA	ICA_POH(frames, FS)	yes	blind source separation; needs non-degenerate RGB variation
GREEN	GREEN(frames)	no	direct green-channel trace; simplest smoke baseline
LGI	LGI(frames)	no	local group-invariant projection; RGB rank matters
PBV	PBV(frames)	no	blood-volume-pulse signature; covariance must be solvable
OMIT	OMIT(frames)	no	orthogonal projection; at least three RGB observations are needed

Names are case-sensitive. The list must contain one or more of these exact strings. An empty list raises a configuration error; any other string raises Not supported unsupervised method!. The optional OMIT method is dispatched like the others even though some older examples list only six methods.

POS and CHROM/ICA use the configured FS internally. CHROM and ICA bandpass around 0.7--2.5 Hz; POS filters around 0.75--3 Hz. FS must be positive and high enough that the filter upper edge is below Nyquist (normal dataset configurations use 30 or 35 Hz). GREEN, LGI, PBV, and OMIT do not receive FS during extraction, but their outputs are still evaluated at that sampling rate. These methods assume meaningful, finite, positive-ish RGB averages and sufficient temporal variation; a constant, empty, NaN, or nearly zero signal is not a valid algorithm test.

Evaluation and outputs

The predictor extracts one BVP per clip, then evaluates windows. With USE_SMALLER_WINDOW: false, it uses the available video length; with true, the window is WINDOW_SIZE * FS frames, capped at the video length. The loop also uses the BVP length, which can be shorter than the input for CHROM. Windows with fewer than 9 frames are explicitly ignored, and very short windows can still fail the downstream filtfilt/peak-detection requirements. Prefer more than nine frames after extraction and substantially longer clips for meaningful HR resolution; the 1.6-second POS/CHROM windows and FFT bins make short clips especially fragile.

FFT uses a periodogram and selects the strongest frequency in approximately 0.6--3.3 Hz before converting to BPM. Exact peak detection uses detected sample peaks and mean inter-peak spacing. FFT is generally the safer first check on short/noisy clips; peak detection requires at least two plausible peaks and clean enough morphology. Shared evaluation detrends and bandpasses both BVP and labels before computing metrics.

Supported metrics are MAE, RMSE, MAPE, Pearson, SNR, MACC, and any metric containing BA (normally BA). An unknown metric raises an error. SNR and MACC are computed alongside HR; BA creates Bland--Altman plots. The configuration derives UNSUPERVISED.OUTPUT_SAVE_DIR under the experiment's log path with a saved_outputs suffix, but the predictor's visible unsupervised artifact is the method/dataset-named Bland--Altman plot directory under the same experiment when BA is requested. Do not assume a per-video BVP file is written there.

Boundaries and recovery

This sub-skill deliberately does not describe loader internals, raw dataset layouts, face detection, cache generation, or visualization formulas. Use the linked sibling skills for those concerns. When a method fails, preserve the original exception and identify the method, clip shape, FS, and effective window before changing preprocessing. Do not “fix” an invalid RGB layout by silently transposing it.

See algorithm details for method assumptions and failure signatures, workflow details for config and run sequencing, and troubleshooting for a failure-oriented decision tree. The bundled smoke check is intentionally source-independent and deterministic; it checks the RGB/FS/output contract, not scientific accuracy or parity with a real dataset.