Analysis options and conventions

This page explains the options shared by the command-line and Python interfaces. CLI spelling uses hyphens, while Python functions use underscores. For example, --axis-convention local corresponds to axis_convention="local".

Analysis flow

For a coordinate input, pyCurves performs these stages:

  1. Load coordinates and select alternate conformations.

  2. Infer a strand/base-pair topology, or read it from Curves input or DSSR JSON.

  3. Fit reference bases to the selected coordinates.

  4. Construct local base and base-pair frames.

  5. Build either a global Curves axis or a local Curves+ axis.

  6. Calculate helical, backbone, groove, curvature, and annotation tables.

  7. Render Curves-style text, JSON, or CSV.

An option can affect only one stage. For example, axis weighting changes axis construction but never adds, removes, or reclassifies a requested base pair.

Topology sources

Inferred topology

Passing a PDB or mmCIF structure without --dssr-json or an explicit .inp file selects coordinate-based topology inference. pyCurves can infer duplex, triplex, and quadruplex arrangements. If no qualifying duplex is found, the inferrer can produce a single-strand topology.

continuous_strands=False keeps separated helical components separate. Set continuous_strands=True (CLI: --continuous-strands) when connected split-chain helices should be treated as one biological helix.

duplex_only=True (CLI: --duplex-only) disables triplex and quadruplex inference and uses the one-to-one duplex path.

Explicit Curves input

A Curves .inp file supplies the strand count, strand directions, residue maps, analysis flags, and optional initial helical values. Pass the coordinate file separately if the input’s file= entry does not resolve:

pycurves helix.inp --pdb structure.pdb

Topology rows accept inclusive range notation such as 1:12. Pair geometry tags use Leontis–Westhof notation, for example [cWW], [tWH], and [cSS]; [unresolved] preserves an explicitly unresolved pair.

DSSR JSON topology

--dssr-json REPORT uses a DSSR report for residue pairing and unit selection while reading coordinates from the PDB/mmCIF input. It cannot be combined with an explicit Curves input or --continuous-strands.

If the report contains one valid unit, it is selected automatically. Otherwise use --dssr-unit KIND:N, where common selectors include multiplet:1, stem:1, helix:2, and pairs:1.

Base fitting

fit controls least-squares fitting of packaged base references to the observed base atoms.

  • None (no CLI override) uses the value inferred or read from the Curves input.

  • True / --fit enables fitting.

  • False / --no-fit disables fitting.

The vectorized batch trajectory engine requires fitting and rejects --no-fit.

Reference-frame convention

standard

Tsukuba/Curves+/3DNA-style base reference frames. This is the default.

legacy

Curves 5.3-compatible base reference frames. Use this when direct numerical compatibility with legacy Curves frames is required.

Select the convention with --frame-convention standard|legacy or the frame_convention Python argument.

The local Curves+ axis is defined on standard frames. Selecting axis_convention="local" therefore forces frame_convention="standard", even if legacy was also requested.

Axis convention

global

The default. Uses the Curves curvilinear-axis path. When minimization is enabled, JAX optimizes the helical-axis variables.

local

Uses the Curves+ local/smooth axis. This mode disables global-axis minimization and trajectory warm starts, and forces standard base frames.

For a Curves 5.3 comparison, use both legacy frames and the global axis:

pycurves structure.pdb \
  --frame-convention legacy \
  --axis-convention global

Axis minimization

mini affects the global-axis path.

  • None reads mini from the Curves input.

  • True / --mini runs global-axis minimization.

  • False / --no-mini constructs the axis once from the input helical values and continues with downstream calculations.

Local-axis mode always disables minimization. Legacy Curves line=.t. and dinu=.t. minimization modes are currently rejected because the JAX optimizer does not implement their alternate objectives.

Axis weighting

axis_weighting=True (CLI: --axis-weighting) smoothly downweights requested pairs whose fitted Curves base origins separate by 4–8 Å. Weighting applies to global optimization and local-axis smoothing when combined-strand analysis is active.

Weighting does not:

  • change the input topology;

  • create or remove a pair;

  • assign a pairing family; or

  • change local base, base-pair, step, or backbone parameters.

Axis-dependent rows report axis_weight. Geometrically unsupported base-pair-axis values are emitted as null.

Grooves, strand combination, and terminal levels

grooves

Controls minor/major groove calculation. None uses the inferred or Curves-input grv value. Curves 5.3-style groove analysis is duplex only; disable it for explicit three- or four-strand inputs.

comb

Controls combined-strand analysis. None uses the inferred or Curves-input comb value. The vectorized batch engine requires combined analysis.

ends

Controls Curves terminal virtual end levels. None uses the inferred or Curves-input value. The vectorized batch engine requires this to be false.

The CLI uses paired boolean flags: --grooves/--no-grooves, --comb/--no-comb, and --ends/--no-ends.

Alternate conformations

--altloc A or altloc="A" retains blank/shared atoms plus the requested one-character alternate-conformation code. Without an explicit selection, Gemmi keeps the first conformer listed in the file. That selection is based on file order, not highest occupancy.

Trajectory topology mode

The regular trajectory engine has two annotation modes:

reference

Keep the reference pair map for all frames. This is the default.

annotate

After calculating a frame from the fixed reference topology, independently detect coordinate-supported pair presence and pairing mode. Missing reference pairs are reported as absent and new pairs use reference_pair=false.

Per-frame annotation does not change the pair map used to calculate geometric parameters.

Trajectory continuity controls

For a minimized global axis, the regular trajectory engine uses two continuity features by default:

warm start

Seed each frame’s optimizer from the preceding processed frame. Disable with --no-warm-start or warm_start=False when diagnosing optimizer branch changes.

axis continuity

Align global-axis direction signs with the first processed frame. Disable with --no-axis-continuity or axis_continuity=False.

Neither feature is used by the local-axis path.