Spectral Features

Descrittori sintetici di frequenza e forma su uno spettro one-sided.

Indice

Modulo ufficiale dev-032
analysis.spectral_features · versione 1.1.0.

Descrittori sintetici di frequenza e forma su uno spettro one-sided.

← Catalogo moduli · Teoria · Framework · Demo e tutorial

Manuale tecnico completo

1. Purpose

analysis.spectral_features calculates compact descriptors from an existing non-negative, one-sided spectrum. It is intended for generic signal, measurement, vibration, acoustics, audio, and laboratory workflows where a spectrum needs a small set of reusable descriptive quantities.

The plugin is deliberately separate from FFT generation. It consumes spectrum.table; it does not call fft, recompute the source spectrum, or implement private source-file readers.

2. Normal workflow

source time series
→ FFT Spectrum / Welch Spectrum
→ canonical spectrum.table
→ Spectral Features
→ summary Dataset
→ report + graph

Use analysis.harmonic_analysis when the scientific question concerns an integer harmonic family and THD. Use analysis.spectral_features when the question concerns the overall distribution of spectral content across frequency.

3. Input

Required Analysis Source contract:

spectrum.table

Required bindings:

The frequency unit must be compatible with Hz through the public Unit Registry. The module preserves the source frequency unit in published frequency-valued descriptors.

The frequency coordinate must be non-negative, strictly increasing, and uniformly spaced. Version 1.1.0 intentionally requires a uniform grid because the amplitude/power bin interpretation is then unambiguous and matches normal FFT/Welch outputs.

4. Input spectral semantics

The Input spectral semantics setting is scientific configuration, not merely a display option.

Amplitude

For an amplitude spectrum A[k], the descriptor weight is:

P[k] = A[k]^2

Power

For an already power-valued spectrum:

P[k] = value[k]

PSD

For a uniformly spaced PSD:

P[k] ∝ PSD[k]

The constant frequency-bin width cancels in normalized descriptors, so the same normalized weighting is used. This is why v1 requires uniform spacing.

The plugin never guesses these semantics from a column name. The user chooses them explicitly.

5. DC handling

Exclude DC bin = yes removes the exact zero-frequency bin before descriptors are calculated. It does not alter the source Dataset.

This is useful when DC offset is not part of the frequency-distribution question. Set it to no when DC is scientifically meaningful.

6. Frequency descriptors

Let normalized power-equivalent weights be:

q[k] = P[k] / sum(P)

Then:

Percentile frequencies are deliberately discrete-bin results in v1. They are not silently interpolated between FFT bins.

7. Shape descriptors

Spectral flatness

geometric_mean(P) / arithmetic_mean(P)

An exact zero power-equivalent bin makes the exact flatness zero. Very small numerical FFT residuals can therefore materially affect the displayed flatness of an otherwise ideal sparse line spectrum; this is mathematically expected and is not hidden by an automatic floor.

Spectral crest factor

max(P) / mean(P)

A highly concentrated spectrum has a high spectral crest factor.

Normalized spectral entropy

H = -sum(q[k] log(q[k])) / log(N)

with zero-weight terms omitted from the sum and N equal to the number of analysed frequency bins. Values near zero describe highly concentrated spectra; larger values describe a broader distribution. Interpretation depends on frequency range, resolution, windowing, and the input semantics.

8. Output Datasets

The module publishes a compact table.generic summary Dataset, default ID:

spectral_features.summary

It contains one row with:

dominant_frequency
spectral_centroid
rms_frequency
spectral_bandwidth
frequency_05
frequency_50
frequency_85
frequency_95
occupied_bandwidth_90
spectral_flatness
spectral_crest_factor
spectral_entropy
bin_count

It also publishes a plot-ready distribution Dataset with ID:

<summary_dataset_id>.distribution

containing frequency, normalized_power, normalized_power_percent, cumulative_power_percent, and relative_power_db. This derived Dataset is reusable by other GX-TXT tools; it is not a private render cache.

The source Dataset remains unchanged. Publication provenance records the source Dataset, stable variable IDs, module version, selected input semantics, and DC policy.

9. Report

spectral_features_report.txt records the actual bindings, units, settings, definitions, calculated descriptor values, and Publication result.

spectral_features_metrics.ini provides a compact machine-readable run summary in addition to the published Dataset.

10. Numerical architecture and graphs

Version 1.1.0 depends on protected CORE math.numeric and discovers NUMERIC_API_v1 through the normal module dependency runtime bridge. Generic operations delegated to the numerical service include:

The module retains the scientific definitions of spectral centroid, flatness, crest factor, entropy, rolloff/occupied bandwidth, and the interpretation of amplitude/power/PSD inputs.

After publication it creates three persistent plot.dataset variants from the distribution Dataset:

There is no module-private renderer or render_cache.mat. Save/reopen, rerender, axes/ranges/scales and normal export are owned by the shared plot.dataset infrastructure.

11. Student Session Generator

The package includes:

gxtxt_numerical_examples_spectral_features_1.0.0.zip

Import it into GX-TXT Numerical Examples. It generates a coherent 4096-sample signal at 4096 Hz containing:

Use a full-record rectangular FFT with mean detrend. With Amplitude semantics and DC excluded, the ideal power-equivalent line weights are 1, 0.25, and 0.0625.

This produces analytically useful reference values including:

The generated STUDENT_GUIDE.md gives the complete exercise and discussion questions.

12. Limitations

Version 1.1.0 intentionally does not provide:

Those are separate scientific concerns.

13. Public GX-TXT APIs used

All product-facing technical text, source comments, tests, and documentation are in English.