signal_stats
Compute scalar metrics (mean, RMS, peak, min/max) from LTspice/ngspice .raw signals. Supports transient, DC, AC, and noise with optional time or sweep windowing to avoid startup bias.
Instructions
Scalar summary of one signal in a .raw result. Use this when you need a single number per metric (average, RMS, peak, etc.) — not a waveform or a trend.
Transient: time-weighted mean, RMS, std, abs-mean, and min/max/pk-pk using trapezoidal integration (RMS = sqrt(∫ y² dt / T)). This is correct on SPICE's adaptive timestep — simple np.mean(y) would overweight densely sampled regions. Optionally restrict to [t_start, t_end]; passing no window averages the whole waveform including any startup transient, which is usually wrong for RMS/mean.
DC: returns min/max/pk-pk and the simple/abs mean over the swept axis, plus sweep_start_used/sweep_end_used/sweep_span. RMS and std are deliberately omitted — they're meaningless on a non-time axis. Use t_start/t_end to restrict the sweep range.
AC: returns magnitude (dB) min/max/mean and phase (deg) min/max. t_start/t_end are rejected for AC — use query_value for a point at a specific frequency.
Noise: returns min/max/pk-pk of the noise spectral density over the frequency axis, plus freq_start_used/freq_end_used. Mean, RMS, std, and duration are omitted — a plain mean of spectral density is dominated by sample clustering and the sweep span, not the circuit; min/max is the useful worst-case reading. t_start/t_end are rejected — pass them via query_value at specific frequencies instead.
Related tools: for rise/fall times use edge_metrics; for overshoot/settling use pulse_response; for period/duty use periodic_metrics; to aggregate .MEAS values across a sweep use measurement_stats.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| step | No | Step index for .step directives | |
| t_end | No | Window end in SPICE notation. Transient only; rejected for AC. | |
| format | No | Response format: 'json' for structured data, 'text' for human-readable | |
| job_id | No | Analyze a specific run of a completed sweep/MC (or single) job instead of a raw_file path; pair with ``run_index``. Lets you summarize a sweep run the same way you'd summarize a standalone raw. | |
| signal | Yes | Signal/trace name (e.g., 'V(out)', 'I(R1)'), or a device operating-point shorthand for an ngspice .save'd parameter: 'm1.gm' / 'm1.vth' (resolves to '@m1[gm]', incl. subcircuit paths like 'x1.m1.gm'). | |
| t_start | No | Window start in SPICE notation (e.g. '1m', '100u'). Transient only. Strongly recommended when computing RMS or average — the startup transient otherwise biases the result. Rejected for AC analysis (time-windowing a frequency sweep is an error). | |
| raw_file | No | Path to .raw result file. Pass this OR ``job_id`` (a job run), not both. | |
| run_index | No | 0-based run to analyze when ``job_id`` is given (default 0). |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| max | No | ||
| min | No | ||
| rms | No | ||
| std | No | ||
| mean | No | ||
| max_db | No | ||
| min_db | No | ||
| signal | No | ||
| mean_db | No | ||
| abs_mean | No | ||
| duration | No | ||
| warnings | No | ||
| max_phase | No | ||
| min_phase | No | ||
| sweep_span | No | ||
| t_end_used | No | ||
| point_count | No | ||
| peak_to_peak | No | ||
| t_start_used | No | ||
| analysis_type | No | ||
| freq_end_used | No | ||
| sweep_end_used | No | ||
| freq_start_used | No | ||
| sweep_start_used | No |