Rg Plugin Reference

For a step-by-step guide to running Rg analysis, see Rg Analysis: Quick Start.

Configuration Reference

All fields for RgRunSettings:

Field	Type	Default	Description
label	str	required	Human-readable run label (must be unique)
selection	str	required	MDAnalysis selection for Rg calculation
calculation_mode	str	"selection"	"selection" for whole-group Rg, "fragments" for per-fragment reduction
fragment_weighting	str	"equal"	"equal" (arithmetic mean) or "mass" (mass-weighted mean). Only valid when calculation_mode="fragments"
save_fragment_distribution	bool	true	Save per-fragment Rg values in NPZ sidecar for distribution analysis
histogram_bins	int	50	Number of bins for fragment/reduced distribution histograms (minimum 2)

Top-level RgSettings contains a single field:

Field	Type	Default	Description
runs	list[RgRunSettings]	required	One or more named Rg runs (at least one required)

Note

Run labels must be unique within a single comparison.yaml. Duplicate labels raise a validation error.

Warning

Unlike RMSD (which defaults selection to "protein and name CA"), Rg has no default selection. You must always specify selection explicitly for each run.

Fragment Mode Reference

Added in version 1.3.0: Fragment-aware Rg calculation was added in PolyzyMD 1.3.0.

Standard selection mode computes one Rg value per frame for the full atom group matched by selection. Fragment mode first computes Rg for each disconnected topological fragment, then reduces those per-fragment values to one per-frame value.

Use fragment mode when your selection includes many independent molecules and you care about the average fragment size rather than the size of the entire multi-molecule cloud.

Fragment mode configuration

plugins:
  rg:
    runs:
      - label: protein_rg
        selection: protein

      - label: polymer_blob_rg
        selection: "resname SBM or resname EGM or resname EGP"
        calculation_mode: fragments
        fragment_weighting: equal

Setting	Meaning
calculation_mode: "selection"	Whole-group Rg
calculation_mode: "fragments"	Per-fragment Rg with reduction
fragment_weighting: "equal"	Arithmetic mean over fragments
fragment_weighting: "mass"	Mass-weighted mean over fragments

How fragment mode reduction works

1. Identify disconnected fragments within the selected atom group

2. Compute fragment-level Rg for each frame

3. Reduce fragment values to one per-frame value using equal or mass weighting

4. Use the reduced timeseries for summary statistics and comparisons

5. Optionally save pooled fragment values in NPZ sidecars for distribution plots

Why Rg Has No Alignment or Reference Fields

Rg is based on mass-weighted distances from the center of mass, so it is translation and rotation invariant.

Because of that, Rg runs do not use RMSD-style fields such as alignment_selection, reference_mode, reference_file, or reference_frame.

Output Files

Results are saved in your project analysis directory:

<projects_directory>/
└── analysis/
    └── rg/
        ├── run_1/
        │   ├── rg_eq10ns.json
        │   ├── rg_Whole Protein_timeseries.npz
        │   └── rg_Protein Backbone_timeseries.npz
        ├── run_2/
        │   ├── rg_eq10ns.json
        │   ├── rg_Whole Protein_timeseries.npz
        │   └── rg_Protein Backbone_timeseries.npz
        ├── run_3/
        │   └── ...
        └── aggregated/
            └── rg_reps1-3_eq10ns.json

Each replicate directory contains:

• JSON summary result for all configured runs

• NPZ sidecars with per-frame timeseries data (one per run)

NPZ sidecar arrays

Each rg_<label>_timeseries.npz may include:

Array	Mode	Description
rg_values	always	Per-frame reduced Rg timeseries (Å)
time_ns	always	Time axis in ns
frames	always	0-indexed frame indices
fragment_rg_values	fragments only	Pooled fragment-level Rg values across all frames
fragment_counts_per_frame	fragments only	Number of fragments detected per frame
fragment_masses	fragments + mass weighting	Fragment masses used for weighted reduction

JSON result structures

Per-replicate result (RgResult):

{
    "config_hash": "abc123...",
    "replicate": 1,
    "equilibration_time": 10.0,
    "equilibration_unit": "ns",
    "selection_string": "protein; resname SBM or resname EGM or resname EGP",
    "n_frames_total": 10000,
    "n_frames_used": 9000,
    "trajectory_files": ["..."],
    "run_results": [
        {
            "run_label": "protein_rg",
            "selection": "protein",
            "calculation_mode": "selection",
            "fragment_weighting": null,
            "mean_rg": 18.234,
            "std_rg": 0.412,
            "median_rg": 18.191,
            "min_rg": 17.087,
            "max_rg": 19.604,
            "final_rg": 18.356,
            "sem_rg": 0.098,
            "correlation_time": 3821.3,
            "correlation_time_unit": "ps",
            "n_independent_frames": 19,
            "statistical_inefficiency": 473.7,
            "n_frames_total": 10000,
            "n_frames_used": 9000,
            "npz_path": ".../rg_protein_rg_timeseries.npz",
            "time_unit": "ns",
            "timestep_ps": 10.0
        },
        {
            "run_label": "polymer_blob_rg",
            "selection": "resname SBM or resname EGM or resname EGP",
            "calculation_mode": "fragments",
            "fragment_weighting": "equal",
            "mean_rg": 8.412,
            "std_rg": 0.231,
            "median_rg": 8.389,
            "min_rg": 7.612,
            "max_rg": 9.103,
            "final_rg": 8.467,
            "sem_rg": 0.054,
            "mean_fragments_per_frame": 50.0,
            "min_fragments_per_frame": 50,
            "max_fragments_per_frame": 50,
            "fragment_mean_rg": 8.445,
            "fragment_std_rg": 1.203,
            "fragment_median_rg": 8.391,
            "fragment_min_rg": 5.102,
            "fragment_max_rg": 12.881,
            "fragment_rg_p10": 7.012,
            "fragment_rg_p25": 7.621,
            "fragment_rg_p50": 8.391,
            "fragment_rg_p75": 9.198,
            "fragment_rg_p90": 10.022,
            "npz_path": ".../rg_polymer_blob_rg_timeseries.npz",
            "time_unit": "ns",
            "timestep_ps": 10.0
        }
    ]
}

Aggregated result (RgAggregatedResult):

{
    "replicates": [1, 2, 3],
    "n_replicates": 3,
    "run_results": [
        {
            "run_label": "protein_rg",
            "selection": "protein",
            "calculation_mode": "selection",
            "fragment_weighting": null,
            "overall_mean": 18.256,
            "overall_sem": 0.044,
            "overall_median": 18.223,
            "per_replicate_means": [18.234, 18.291, 18.244],
            "per_replicate_stds": [0.412, 0.398, 0.424],
            "per_replicate_medians": [18.191, 18.262, 18.216],
            "reduced_histogram_edges": [17.0, 17.04, "..."],
            "reduced_histogram_density_mean": [0.012, 0.034, "..."],
            "reduced_histogram_density_sem": [0.001, 0.002, "..."]
        },
        {
            "run_label": "polymer_blob_rg",
            "selection": "resname SBM or resname EGM or resname EGP",
            "calculation_mode": "fragments",
            "fragment_weighting": "equal",
            "overall_mean": 8.432,
            "overall_sem": 0.021,
            "overall_median": 8.401,
            "per_replicate_means": [8.412, 8.445, 8.439],
            "per_replicate_stds": [0.231, 0.218, 0.225],
            "per_replicate_medians": [8.389, 8.421, 8.394],
            "overall_mean_fragments_per_frame": 50.0,
            "per_replicate_mean_fragments_per_frame": [50.0, 50.0, 50.0],
            "fragment_histogram_edges": [5.0, 5.16, "..."],
            "fragment_histogram_density_mean": [0.005, 0.012, "..."],
            "fragment_histogram_density_sem": [0.001, 0.002, "..."],
            "reduced_histogram_edges": [7.8, 7.83, "..."],
            "reduced_histogram_density_mean": [0.021, 0.045, "..."],
            "reduced_histogram_density_sem": [0.002, 0.003, "..."]
        }
    ]
}

Plot Types

The Rg plugin generates figures via polyzymd compare plot-all.

Plot output	Description
rg_timeseries_<run>.png	Mean Rg vs time with SEM shading, one figure per run
rg_comparison_<run>.png	Grouped bar chart of mean Rg across conditions, one figure per run
rg_distribution_<run>.png	Distribution view. Selection mode: reduced distribution panel only. Fragment mode: reduced + pooled fragment distributions

Distribution plots are generated for runs that include histogram data in aggregated results.

Plot settings in comparison.yaml:

plot_settings:
  rg:
    show_per_replicate: false    # Overlay individual replicate traces
    figsize: [10, 6]             # Default figure size (bar charts)
    timeseries_figsize: [12, 5]  # Timeseries figure size

Common CLI Options

Option	Default	Description
-f, --file	comparison.yaml	Path to comparison configuration
--eq-time	0ns	Equilibration time to skip
--recompute	off	Ignore cached results and recompute
--format	table	Output format (table or json)
-o, --output	(none)	Save formatted output to file
-q, --quiet	off	Suppress INFO messages
--debug	off	Enable DEBUG logging

Replicates are configured per condition in comparison.yaml:

conditions:
  - label: "no_polymer"
    config: "configs/no_polymer.yaml"
    replicates: [1, 3, 5]

Troubleshooting

“Selection matched no atoms”

When a run selection matches zero atoms, that run is skipped with a warning. Analysis continues for runs and conditions with valid data.

If unexpected:

• Confirm residue numbering and atom naming in your topology

• Check selection syntax directly against your system

• Re-run with --debug for detailed diagnostics

“At least one Rg run must be defined”

Cause: plugins.rg.runs is missing or empty.

Fix: add at least one run with label and selection.

“Rg run labels must be unique”

Cause: duplicate run labels.

Fix: assign a unique label to each run.

“Equilibration removed all frames”

Cause: --eq-time exceeds trajectory duration.

Fix: lower equilibration time or verify simulation completion.

Very large Rg fluctuations (> 5 Å std)

Cause: often unfolding, large flexibility, or an overly broad selection.

Fix:

• Validate the selection (whole protein vs backbone vs core)

• Check trajectory integrity

• Inspect timeseries for transitions or discontinuities

“Low statistical reliability” warning

Cause: correlation time is long relative to trajectory length.

This is informational. Consider longer simulations or more replicates.

Missing replicate data

Message: Skipping replicate N: trajectory data not found

Cause: trajectory files are missing or replicate is incomplete.

Fix: verify simulation output paths and replicate status.

Control condition missing for a run in fragment-mode workflows

Message: control has no data for a run and comparison falls back to all-vs-all pairwise testing for that run.

Cause: control selection matched no atoms for that run.

Behavior: expected in mixed run sets (for example, polymer-only runs with a no-polymer control).

Rg vs Other Metrics

Rg vs RMSD

Feature	Rg	RMSD
Measures	Structural compactness (mass-weighted size)	Deviation from a reference structure
Output	One value per frame (timeseries)	One value per frame (timeseries)
Reference	None required	Required (centroid, average, frame, or external)
Alignment	Not required	Required
Configuration	label + selection	label + selection + alignment + reference
Direction labels	compaction / expansion / unchanged	stabilizing / destabilizing / unchanged
Best for	Compaction, swelling, folding state shifts	Drift and reference-relative stability

Rg vs RMSF

Feature	Rg	RMSF
Measures	Global compactness over time	Per-residue positional fluctuation
Primary output	Timeseries	Residue profile
Best question	Is the structure compacting or expanding?	Which regions are flexible or rigid?