Framework per l’analisi spettrale

Il framework non è un altro metodo spettrale. È l'infrastruttura che rende i metodi riproducibili: identifica i Dataset, lega le variabili, legge i dati in modo backend-neutral, pubblica risultati e conserva provenance e grafici.

1. Flusso architetturale

Acquisition / imported Dataset
        ↓
Canonical Dataset + stable dataset_id / variable_id
        ↓
Analysis Source + bindings + Selection / Temporal Set
        ↓
Table Stream / Canonical Dataset access
        ↓
NUMERIC_API_v1 / SIGNAL_API_v1 + module-specific semantics
        ↓
Dataset Publication API v2
        ↓
spectrum.table / table.generic / timeseries.table
        ↓
Plot Dataset / Graph Provider / Render Cache
        ↓
Session persistence + provenance

2. Dataset canonico

Il Dataset è identificato da un dataset_id stabile. Le variabili sono identificate dalla coppia dataset_id + variable_id. Percorsi CSV, oggetti HDF5 e colonne fisiche sono dettagli di storage e non devono diventare identità scientifiche.

3. Variable Schema v3

Lo schema descrive dtype, rank, shape, dimensioni logiche, coordinate, ruolo coordinate/data, assi uniformi e gruppi. Questo consente allo stesso codice di lavorare su CSV, HDF5 e altri provider senza conoscere il layout interno.

4. Analysis Source e binding

Un modulo dichiara sorgenti logiche come primary. I binding indicano quali variabili del Dataset svolgono il ruolo di tempo, segnale, frequenza, PSD, ecc. Il modulo non deve cercare un “dataset primario” privato o aprire file a caso: deve usare la sorgente scelta dalla Session.

5. Selection e Temporal Set

Una Dataset Selection descrive una selezione persistente di dati. Un Temporal Set descrive segmenti o finestre riusabili nel tempo. Sono oggetti di Session distinti dalla FFT. Welch, Time-Dependent FFT e Cross-Spectral Transfer usano in particolare window_set.

6. Lettura dei dati

CANONICAL_DATASET_API_v2 è il contratto generale di accesso. TABLE_STREAM_API_v3 è la facciata streaming per variabili rank-1 che condividono una dimensione riga. Il modulo può così leggere chunk limitati senza caricare necessariamente l'intero Dataset in RAM.

7. Calcolo scientifico condiviso

NUMERIC_API_v1 fornisce primitive matematiche generiche. SIGNAL_API_v1 fornisce matematica di segnale e sistemi: convolution, correlation, filtering, spectral estimators, STFT, cepstrum, analytic signal e metriche. Il modulo Analysis aggiunge invece semantica del workflow, configurazione, output e interpretazione.

8. Publication

I risultati strutturati vengono registrati tramite DATASET_PUBLICATION_API_v2. Il producer dichiara Dataset, dimensioni e variabili; CORE sceglie e gestisce il provider di storage, calcola SHA-256 e committa il registry solo dopo il successo.

9. spectrum.table

spectrum.table è il contratto usato per risultati spettrali tabellari. Questo permette una pipeline: FFT/Welch producono uno spettro; Harmonic, Fractional-Octave o Spectral Features possono consumarlo senza ricomputare la trasformata temporale.

10. Grafica persistente

I grafici scientifici vengono gestiti tramite Graph Provider e/o plot.dataset. Un PlotSpec usa Dataset ID e Variable ID, non un'immagine PNG come identità. Le varianti permettono di cambiare presentazione senza necessariamente rifare il calcolo scientifico.

11. Render Cache

I moduli che separano calcolo e rendering possono riutilizzare una cache scientifica compatibile. render_only significa “usa risultati esistenti e ridisegna”; non significa “ricalcola più velocemente”.

12. Parallel execution

Quando un modulo supporta worker paralleli, la policy e le risorse restano sotto PARALLEL_EXECUTION_API_v1. Il modulo non dovrebbe inventare una seconda politica di worker scollegata dal framework.

13. Dove trovare i dettagli