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)
mean_peak_height	peak_mag	Mean correlation peak magnitude per grid cell

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

Instantaneous Statistics

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

Statistic	Output Fields	Description
inst_vorticity	vorticity	Per-frame out-of-plane vorticity
inst_divergence	divergence	Per-frame velocity divergence
inst_stresses	u_prime, v_prime, uu_inst, vv_inst, uv_inst	Fluctuations and per-frame Reynolds stresses
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	Local swirling strength. Values near \|1\| indicate strong vortex cores.
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 calibrated instantaneous or merged data.
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

# Compute for ensemble data
pivtools-cli statistics --type-name ensemble

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

Output

Results are saved in a statistics/ subdirectory under each camera folder.

Output Directory

base_path/
  calibrated_piv/{num_frame_pairs}/
    Cam1/
      instantaneous/              # Original frame data
      statistics/
        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
          ...

statistics:
  type_name: instantaneous      # "instantaneous" or "ensemble"
  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)
    mean_peak_height: false     # Mean correlation peak magnitude

    # Instantaneous (per-frame)
    inst_vorticity: false       # Per-frame vorticity
    inst_divergence: false      # Per-frame divergence
    inst_stresses: false        # Per-frame fluctuations and stresses
    inst_gamma: false           # Gamma vortex criteria

Next: Create Videos

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

Continue to Video Maker