Vector Statistics

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

Turbulence Analysis Made Simple

The statistics module processes your instantaneous velocity frames to compute time-averaged quantities and per-frame derived fields. Results can be viewed directly in the Results Viewer.

Mean

Time-averaged fields

Stresses

Reynolds tensor

TKE

Turbulent energy

Vortices

Gamma detection

Overview

PIVTools computes two categories of statistics: mean (time-averaged) quantities that summarise your entire time series, and instantaneous per-frame quantities that require calculation at each timestep.

Mean Statistics

Computed once across all frames. Results are single fields representing time-averaged quantities.

Mean velocity components
Reynolds stress tensor
Turbulent kinetic energy
Mean vorticity & divergence

Instantaneous Statistics

Computed for each frame. Results are time series of derived fields that can be viewed frame-by-frame.

Per-frame stress tensor
Instantaneous vorticity
Instantaneous divergence
Gamma vortex criteria

Data Sources

Statistics can be calculated from either per-camera data or merged data. Choose your source in the Statistics panel based on your workflow needs.

Mean Statistics

Mean statistics are time-averaged quantities computed across all frames in your dataset. These are the fundamental outputs for characterising steady-state flow behaviour.

Statistic	Output Fields	Description
mean_velocity	ux, uy	Time-averaged velocity components (add 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 components (add ww, uw, vw for stereo)

Reynolds Stress Tensor

The Reynolds stress tensor quantifies turbulent momentum transport. Components are computed as:

uu = mean(u' * u')

Streamwise normal stress

vv = mean(v' * v')

Cross-stream normal stress

uv = mean(u' * v')

Shear stress

Where u' = u - U (fluctuation = instantaneous - mean)

Stereo (3D) Statistics

For stereo PIV data with a uz component, additional stress terms are computed:ww,uw, andvw. TKE includes all three components: 0.5*(u'u' + v'v' + w'w').

Instantaneous Statistics

Instantaneous statistics are computed for each frame, creating time series of derived quantities. These can be viewed frame-by-frame in the Results Viewer.

Statistic	Output Fields	Description
inst_velocity	ux, uy	Per-frame velocity (preserved from input)
inst_stresses	uu_inst, vv_inst, uv_inst	Per-frame Reynolds stress tensor
inst_vorticity	vorticity	Per-frame out-of-plane vorticity
inst_divergence	divergence	Per-frame velocity divergence
inst_gamma	gamma1, gamma2	Gamma vortex detection criteria

Gamma Vortex Detection

The Gamma criteria (Graftieaux et al.) detect vortex cores without relying on velocity gradients, making them robust for noisy PIV data.

Gamma 1 (gamma1)

Measures local swirling strength. Values near |1| indicate strong vortex cores.

Range: -1 to +1 (sign = rotation direction)

Gamma 2 (gamma2)

Corrects for local convection velocity. Better isolates true vortex cores.

Range: -1 to +1 (sign = rotation direction)

Gamma Radius Parameter

The gamma_radius parameter (default: 5) controls the size of the neighbourhood used for calculation. Larger values smooth results but may miss small vortices. Typical range: 3-10 grid points.

GUI Workflow

The Statistics panel in the Results Viewer provides an intuitive interface for selecting and calculating statistics from your PIV data.

Open the Results Viewer

Navigate to the Results Viewer and select calibrated instantaneous or merged instantaneous data as your source.

Expand the Statistics Panel

Click the "Statistics" button to expand the statistics controls. This panel only appears for eligible data sources.

Select Statistics to Calculate

Check the boxes for each statistic you want to compute. Statistics are grouped into "Time-Averaged" and "Instantaneous" categories.

Configure Gamma Radius (Optional)

If calculating gamma criteria, adjust the gamma_radius parameter. Default is 5 grid points. Larger values smooth results.

Choose Data Source

Select whether to process per-camera data, merged data, or both. The toggle shows available options based on your dataset.

Start Calculation

Click "Calculate Statistics" to begin processing. A progress bar shows completion status for each camera and statistic type.

View Mean Statistics

After calculation, select variables with the mean:prefix in the variable dropdown to view time-averaged results.

View Instantaneous Statistics

Select variables with the inst_stat:prefix to view per-frame calculated quantities with full frame navigation.

CLI Usage

For batch processing, use the CLI to calculate statistics across all active paths.

Statistics CLI Command

# Calculate statistics for all active paths
pivtools-cli statistics

# Compute for specific camera only
pivtools-cli statistics --camera 1

# Compute for merged data (modern flag)
pivtools-cli statistics --source-endpoint merged

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

# Specify workflow: per_camera, after_merge, both, or stereo
pivtools-cli statistics --source-endpoint merged --workflow after_merge

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

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

# Legacy flags (deprecated but still supported)
# pivtools-cli statistics --merged    # use --source-endpoint merged
# pivtools-cli statistics --stereo    # use --source-endpoint stereo

# The CLI will:
# 1. Read statistics configuration from config.yaml
# 2. Process each active_path (or selected paths with -p)
# 3. Calculate selected statistics for each camera
# 4. Save results to statistics/ subdirectory

GUI vs CLI Comparison

GUI Mode

- One base_path at a time
- Interactive statistic selection
- Real-time progress display
- Immediate visualisation

CLI Mode

- All active_paths processed
- Uses config.yaml settings
- Batch processing
- Suitable for automation

Recalculation After Transforms

If you apply transforms to your vector data, you must recalculate statistics. The old statistics files are no longer valid after data transformation.

YAML Configuration

Statistics settings are stored in the statisticssection of config.yaml.

statistics:
  type_name: instantaneous    # Temporal type: "instantaneous" or "ensemble"
  source_endpoint: regular    # Data source: "regular", "merged", or "stereo"
  workflow: per_camera        # Workflow: "per_camera", "after_merge", "both", or "stereo"
  gamma_radius: 5             # Neighbourhood size for gamma calculation
  save_figures: true          # Generate PNG visualisations

  # Enable/disable individual statistics
  enabled_methods:
    # Time-averaged (mean) statistics
    mean_velocity: true       # Mean ux, uy (and uz for stereo)
    mean_vorticity: true      # Mean omega
    mean_divergence: true     # Mean div(u)
    mean_tke: true            # Turbulent kinetic energy
    mean_stresses: true       # Reynolds stress tensor (uu, vv, uv; uw, vw, ww for stereo)

    # Instantaneous (per-frame) statistics
    inst_velocity: false      # Keep original velocity
    inst_stresses: false      # Per-frame stress tensor
    inst_vorticity: false     # Per-frame vorticity
    inst_divergence: false    # Per-frame divergence
    inst_gamma: false         # Gamma vortex criteria

# Note: Legacy names are also supported:
# - reynolds_stress -> mean_stresses
# - normal_stress -> mean_stresses
# - inst_fluctuations -> inst_stresses
# - tke -> mean_tke

Configuration Parameters

Parameter	Type	Description
type_name	string	Temporal type: "instantaneous" or "ensemble"
source_endpoint	string	Data source: "regular" (per-camera), "merged", or "stereo"
workflow	string	Workflow: "per_camera", "after_merge", "both", or "stereo"
gamma_radius	integer	Grid points for gamma calculation (default: 5)
save_figures	boolean	Generate PNG visualisations of results
enabled_methods	dict	Enable/disable individual statistics

Output Files

Statistics results are saved in a statisticssubdirectory under each camera folder.

Output Directory Structure

base_path/
├── calibrated_piv/
│   └── {num_frame_pairs}/
│       └── Cam1/
│           ├── instantaneous/        # Original frame data
│           │   ├── 00001.mat
│           │   └── ...
│           │
│           └── statistics/           # STATISTICS OUTPUT
│               ├── mean_stats/
│               │   └── mean_stats.mat    # All mean statistics
│               │
│               ├── instantaneous_stats/  # Per-frame statistics
│               │   ├── 00001.mat         # Frame 1 inst stats
│               │   ├── 00002.mat         # Frame 2 inst stats
│               │   └── ...
│               │
│               └── figures/              # PNG visualisations
│                   ├── Run_1_Mean_Ux.png
│                   ├── Run_1_Mean_Uy.png
│                   ├── Run_1_TKE.png
│                   ├── Run_1_uu_stress.png
│                   └── ...

mean_stats.mat

Single file containing all time-averaged statistics. Each field is a 2D array matching your vector grid dimensions.

instantaneous_stats/

One file per frame containing per-frame calculated quantities. Same format as your original vector files.

figures/

PNG visualisations of each statistic, organised by run number. Useful for quick inspection without loading the viewer.

Back to Results Viewer

Return to the main Results Viewer page to explore all viewing and post-processing options, or check the data type compatibility table.

Back to Results Viewer