Pipeline Outputs and Concepts

This page documents the data structures and terminology used throughout face-rhythm: how a session is organized, what a pipeline run produces, and how to interpret the files written to disk.

Project layout on disk

A face-rhythm project is a single directory created by face_rhythm.project.prepare_project(). After a run completes, that directory contains:

<directory_project>/
├── config.yaml          # parameters used by every module
├── run_info.json        # lightweight metadata produced by every module
├── analysis_files/      # per-module HDF5 outputs (the data products)
│   ├── Dataset_videos.h5
│   ├── ROIs.h5
│   ├── PointTracker.h5
│   ├── VQT_Analyzer.h5
│   └── TCA.h5
└── visualizations/      # figures saved by Figure_Saver

Each pipeline module appends a section keyed by class name (for example, PointTracker) to config.yaml and run_info.json, and writes its data arrays to the matching <ClassName>.h5 file under analysis_files/.

Run output dict

face_rhythm.pipelines.pipeline_basic() returns a small results dictionary that points at the artifacts on disk; the substantive arrays are not held in memory. The keys are:

  • path_config (str) — path to config.yaml.

  • path_run_info (str) — path to run_info.json.

  • directory_project (str) — root project directory.

  • SEED (int) — random seed used for the run.

  • params (dict) — the full parameter dictionary that was executed.

Pipeline stage outputs

Dataset_videos.h5 — face_rhythm.data_importing

A handle on the raw video set used for the run.

  • example_image — a single representative frame, used downstream for ROI drawing and visualization.

The accompanying run_info.json block records frame_rate, num_frames_total, frame_height_width, num_channels, and the per-video metadata.

ROIs.h5 — face_rhythm.rois

The face mask(s) and the seed grid of points to track.

  • mask_images — boolean masks for each ROI.

  • roi_points — vertex coordinates of each user-drawn ROI polygon.

  • point_positions — (n_points, 2) array of (x, y) coordinates used as initial point locations.

  • exampleImage — the frame the ROIs were drawn on.

  • num_points — total number of tracked points.

PointTracker.h5 — face_rhythm.point_tracking

Output of optical-flow point tracking across all videos in the session.

  • points_tracked — point-tracking time series dict keyed by video index ("0", "1", …); each value is an array of shape (n_frames, n_points, 2).

  • violations — sparse COO arrays (row, col, data, shape) per video flagging frames where displacements crossed the outlier threshold and points were frozen.

  • point_positions — initial point grid (carried through from ROIs.h5).

  • neighbors, mesh_d0, mask — internal mesh structure used by the elastic point tracker.

run_info adds num_videos, per-video num_frames, num_frames_total, num_points, and violation_fraction.

VQT_Analyzer.h5 — face_rhythm.spectral_analysis

Variable-Q transform spectrograms of the per-point displacement traces.

  • spectrograms — dict keyed by video index; each value has shape (2, n_points, n_freq_bins, n_frames_downsampled), where the leading axis is the (x, y) displacement direction.

  • x_axis — frame indices corresponding to each spectrogram column (after temporal downsampling).

  • frequencies — center frequencies of the VQT filter bank.

  • VQT — the filter bank itself (filters and wins) used to compute the spectrograms.

  • point_positions — point grid carried through from earlier stages.

TCA.h5 — face_rhythm.decomposition

Tensor component analysis (CP-style) decomposition of the spectrogram tensor.

  • factors — the raw factor matrices, one per tensor dimension, in the same dimension order used during fitting.

  • factors_rearranged — the factors after any concatenations along the xy, complex, and dictionary-element axes have been undone, giving per-dimension factors in their natural shape.

  • names_dims_array / names_dims_array_preDecomp — the axis names (e.g. ['xy', 'points', 'frequency', 'time']) corresponding to each factor, before and after rearrangement.

  • name_dim_dictElements / name_dim_dictElements_preDecomp — the name of the dictionary axis (typically 'trials') before and after rearrangement.

run_info adds num_dictElements along with the dimension-name metadata.

Cross-references