Vector Statistics

Calculate mean velocities, Reynolds stresses, turbulent kinetic energy, and vortex detection metrics from your PIV time series.

Overview

PIVTools computes two categories of statistics: mean (time-averaged) quantities across all frames, and instantaneous per-frame derived fields. Results are viewable in the Results Viewer using the mean: andinst_stat: variable prefixes.

Mean velocity, vorticity, divergence, TKE, Reynolds stresses
Per-frame vorticity, divergence, stresses, and gamma vortex criteria
Stereo-aware: additional ww, uw, vw stresses and 3D TKE when uz present
Works on per-camera, merged, or stereo data sources

Mean Statistics

Time-averaged quantities computed once across all frames. Each produces a single 2D field.

Statistic	Output Fields	Description
mean_velocity	ux, uy	Time-averaged velocity (+uz for stereo)
mean_vorticity	vorticity	Mean out-of-plane vorticity (dv/dx - du/dy)
mean_divergence	divergence	Mean velocity divergence (du/dx + dv/dy)
mean_tke	tke	Turbulent kinetic energy: 0.5*(u'u' + v'v')
mean_stresses	uu, vv, uv	Reynolds stress tensor (+ww, uw, vw for stereo)
correlation_quality	nan_pct, peak_ratio_median, peak_mag_mean	Correlation diagnostics. Uncalibrated data only -- see below

Reynolds Stress Computation

Stresses are computed from fluctuations: uu = mean(u' * u') whereu' = u - U (instantaneous minus mean). TKE includes all available components (2D or 3D).

Correlation Diagnostics

The correlation_quality statistic reports how well the correlation itself performed, rather than anything about the flow. Use it to decide whether a dataset is worth trusting before you interpret the velocities.

Uncalibrated data only. The quality channels are written by the PIV pass and dropped when calibration is applied, which keeps only ux,uy and b_mask. Point the viewer at an uncalibrated source, or setstatistics.process_uncalibrated: true for a CLI run.

Field	Meaning
nan_pct	Percentage of frames in which this grid cell was rejected. High values mark regions the correlation never resolved -- glare, low seeding, or out-of-plane loss.
peak_ratio_median	Median ratio of the first to second correlation peak. Values near 1 mean the true peak was not clearly distinguishable from its competitor.
peak_mag_mean	Mean correlation peak magnitude. Low values indicate weak correlation, usually from insufficient particle image density.

Each field is written as a map plus a per-frame time series incorr_quality_timeseries.mat, so you can see both where the correlation struggled and when. In the Results Viewer on an uncalibrated source the Statistics button reads Calculate Diagnostics and the panel header becomes Correlation Diagnostics.

Instantaneous Statistics

Per-frame derived fields. Results are time series viewable frame-by-frame in the Results Viewer.

Statistic	Output Fields	Description
inst_velocity	ux, uy	Per-frame velocity copied into the inst stats output
inst_vorticity	vorticity	Per-frame out-of-plane vorticity
inst_divergence	divergence	Per-frame velocity divergence
inst_stresses	uu_inst, vv_inst, uv_inst	Per-frame Reynolds stresses (fluctuations u_prime, v_prime are computed internally, not stored)
inst_gamma	gamma1, gamma2	Gamma vortex detection criteria (Graftieaux et al.)

Gamma Vortex Detection

The Gamma criteria detect vortex cores without relying on velocity gradients, making them robust for noisy PIV data. Both output values range from -1 to +1 (sign indicates rotation direction).

Field	Purpose
gamma1	Graftieaux Γ1 criterion: a normalised, gradient-free measure of vortex-centre location. Values near \|1\| indicate a vortex centre.
gamma2	Corrects for local convection velocity. Better isolates true vortex cores.

gamma_radius

Controls the neighbourhood size (default: 5 grid points). Larger values smooth results but may miss small vortices. Typical range: 3-10.

GUI Workflow

Step	Action
1	Open the Results Viewer and select instantaneous or merged data. Calibrated sources give the full statistic set; uncalibrated sources give the correlation diagnostics only.
2	Expand the Statistics panel and check the statistics to compute.
3	Adjust gamma_radius if computing gamma criteria (default: 5).
4	Choose data source: per-camera, merged, or both.
5	Click "Calculate Statistics". Progress is shown per camera.
6	The viewer automatically switches to the statistics data source upon completion. Mean statistics (mean:) also appear in the variable dropdown when viewing instantaneous data.

Recalculate After Transforms

If you apply transforms to your vector data, statistics must be recalculated. The old statistics files are invalidated by any data transformation.

CLI Usage

The CLI processes all active paths using the statistic selections saved in config.yaml.

Statistics CLI

# Calculate statistics for all active paths
pivtools-cli statistics

# Compute for merged data
pivtools-cli statistics --source-endpoint merged

# Compute for stereo data
pivtools-cli statistics --source-endpoint stereo

# Process specific paths
pivtools-cli statistics -p 0,1

Output

Results are saved under a top-level statistics/ tree, beside calibrated_piv/ rather than inside it. Diagnostics computed from uncalibrated data get their own parallel tree so they never mix with calibrated results.

Output Directory

base_path/
  statistics/{num_frame_pairs}/
    Cam1/instantaneous/
      mean_stats/
        mean_stats.mat            # All mean statistics in one file
      instantaneous_stats/
        00001.mat                 # Frame 1 inst stats
        00002.mat                 # Frame 2 inst stats
        ...
      figures/                    # PNG visualisations (if enabled)
        Run_1_Mean_Ux.png
        Run_1_TKE.png
        ...
    stereo/Cam1_Cam2/instantaneous/   # Stereo sources
  statistics/uncalibrated/{num_frame_pairs}/
    Cam1/instantaneous/           # Correlation diagnostics only

statistics:
  type_name: instantaneous      # "instantaneous" only -- see note above
  source_endpoint: regular      # "regular", "merged", or "stereo"
  gamma_radius: 5               # Neighbourhood size for gamma (default: 5)
  save_figures: true            # Generate PNG visualisations

  enabled_methods:
    # Time-averaged (mean)
    mean_velocity: true         # Mean ux, uy (+uz for stereo)
    mean_vorticity: true        # Mean vorticity
    mean_divergence: true       # Mean divergence
    mean_tke: true              # Turbulent kinetic energy
    mean_stresses: true         # Reynolds stresses (uu, vv, uv; +ww, uw, vw)
    correlation_quality: false  # Correlation diagnostics (uncalibrated only)

    # Instantaneous (per-frame)
    inst_velocity: true         # Per-frame ux, uy in inst stats output
    inst_vorticity: true        # Per-frame vorticity
    inst_divergence: true       # Per-frame divergence
    inst_stresses: true         # Per-frame fluctuations and stresses
    inst_gamma: true            # Gamma vortex criteria

Next: Create Videos

Animate your velocity fields and computed statistics as high-quality MP4 videos.

Continue to Video Maker