diff --git a/README.md b/README.md new file mode 100644 index 0000000..f8eb638 --- /dev/null +++ b/README.md @@ -0,0 +1,145 @@ +# fitseg + +Legge un CSV `t_ms,T_C,dT_C` (temperatura di un sensore IR che si scalda e si raffredda), riconosce quando c'è **riscaldamento** (gradini di flusso in entrata) e quando c'è **raffreddamento**, divide il tempo in **domini** e trova per ogni dominio e ogni serie l'equazione che approssima meglio i dati, con minimi quadrati non lineari. + +Risultato per ogni dominio: modello scelto, parametri con intervallo di confidenza al 95 %, metriche (RMSE, R², AICc, BIC, autocorrelazione dei residui), grafici e un report in Markdown. + +## Requisiti + +- Python ≥ 3.11 +- [uv](https://docs.astral.sh/uv/) (consigliato): `curl -LsSf https://astral.sh/uv/install.sh | sh` +- Dipendenze: `numpy`, `scipy`, `matplotlib` (più `pytest` e `ruff` per lo sviluppo) + +## Installazione + +```bash +uv venv .venv +uv pip install -e ".[dev]" +``` +Il programma si lancia con `.venv/bin/fitseg` (oppure `source .venv/bin/activate` e poi `fitseg`). + +## Dati di ingresso + +Un CSV con intestazione, tempo crescente e una o più serie: + +``` +t_ms,T_C,dT_C +151,22.90,0.20 +301,22.63,0.03 +``` +I nomi delle colonne, l'unità del tempo (`ms` o `s`) e il separatore sono in [config.toml](config.toml), sezione `[dati]`. + +I CSV di prova vengono dal generatore `../gen_data` (repository separato). I test usano i seed 1, 2 e 3 in `dati/` (cartella ignorata da git): + +```bash +mkdir -p dati +for s in 1 2 3; do + (cd ../gen_data && .venv/bin/python genera.py config.toml --seed $s -o ../EquationMiner/dati/gen_$s.csv) +done +``` + +## Uso + +```bash +fitseg domini dati/gen_1.csv # solo i domini: tabella a schermo + lavoro/domini.toml +fitseg analizza dati/gen_1.csv # domini + fit + scelta + report in lavoro/out/ +fitseg modelli # catalogo dei modelli con equazioni e parametri +fitseg valuta lavoro/out/modello_finale.json --t 10 30 60 # valuta il modello a tratti in questi istanti +``` + +Le opzioni globali `--config PATH` (default `config.toml`) e `--lavoro DIR` (default `lavoro`) vanno **prima** del sottocomando: + +```bash +fitseg --config altra.toml --lavoro prova1 analizza dati/gen_2.csv +``` + +### Correggere i domini a mano + +`fitseg domini` (e `analizza`) scrive la proposta automatica in `lavoro/domini.toml`: + +```toml +[[dominio]] +tipo = "riscaldamento" # riposo | riscaldamento | raffreddamento +t0_s = 15.8 # incluso +t1_s = 17.76 # escluso (l'ultimo dominio arriva a fine dati) +``` +Modifica i tempi, aggiungi o togli blocchi `[[dominio]]` (devono restare contigui) e rilancia: + +```bash +fitseg analizza dati/gen_1.csv --domini lavoro/domini.toml +``` + +## Cosa produce + +Tutto in `lavoro/` (ignorata da git): + +| File | Contenuto | +|---|---| +| `domini.toml` | proposta dei domini (o quelli che hai usato) | +| `dati.csv` | copia del CSV analizzato | +| `out/report.md` | per dominio e serie: modello scelto, parametri ± IC 95 %, metriche, tabella di confronto di tutti i modelli | +| `out/equazioni.md` | solo le equazioni scelte | +| `out/modello_finale.json` | modello e parametri per dominio e serie (input di `valuta`) | +| `out/risultati.json` | tutti i fit con tutte le metriche | +| `out/fit_.png` | dati, fit a tratti (un colore per tipo di dominio) e residui | + +### Come leggere il report + +- **Scelto**: il modello con meno parametri tra quelli equivalenti per AICc (ΔAICc ≤ 2) e validi (convergenti, parametri lontani dai limiti, identificabili). +- **modello non adeguato**: l'RMSE supera 1.3 volte il rumore stimato. Il modello migliore disponibile non spiega tutto: guarda l'ACF1 dei residui. +- **Indeterminato**: nessun modello è valido, oppure il dominio ha meno di `n_min_punti` campioni. +- Nel raffreddamento, `τ` è la costante di tempo e `c` la temperatura asintotica (≈ ambiente per `T_C`, ≈ 0 per `dT_C`). + +## Come funziona + +1. **Domini**: un salto positivo tra due campioni consecutivi sopra `soglia_gradino_c` è un gradino di riscaldamento. Prima del primo gradino il dominio è `riposo`, tra due gradini `riscaldamento`, dopo l'ultimo `raffreddamento`. +2. **Fit**: in ogni dominio, con il tempo traslato a `t' = t − t0`, si fittano tutti i modelli di `modelli_abilitati` con `scipy.optimize.least_squares` e perdita robusta. +3. **Scelta**: regola automatica (SPEC §5.3), senza intervento umano. + +Dettagli, modelli e limiti: [docs/SPEC.md](docs/SPEC.md). Uso esteso: [docs/USO.md](docs/USO.md). + +## Modelli + +| Id | Equazione | +|---|---| +| `costante` | `y = a` | +| `lineare` | `y = a + b·t'` | +| `quadratico` | `y = a + b·t' + c·t'²` | +| `esp_decad` | `y = c + A·exp(−t'/τ)` | +| `esp_doppio` | `y = c + A1·exp(−t'/τ1) + A2·exp(−t'/τ2)` | +| `logistica` | `y = c + A / (1 + exp(−(t'−t_m)/w))` | + +Per aggiungerne uno: nuova voce in `MODELLI` di [src/fitseg/modelli.py](src/fitseg/modelli.py), nuova riga in SPEC §4 e nome in `modelli_abilitati`. + +## Configurazione + +Tutti i valori sono in [config.toml](config.toml); non c'è nessun default nel codice (chiave mancante = errore). Quelle che conviene conoscere: + +| Chiave | Effetto | +|---|---| +| `[domini] soglia_gradino_c` | salto minimo che segna un gradino (20 °C); da adattare se i gradini reali sono più piccoli | +| `[domini] scarta_dopo_salto_n` | campioni esclusi all'inizio di un dominio dopo un gradino (transizione del sensore) | +| `[domini] n_min_punti` | campioni minimi per dominio | +| `[fit] modelli_abilitati` | modelli provati in ogni dominio | +| `[fit] soglia_delta_aicc` | entro questa differenza vince il modello con meno parametri | +| `[fit] rmse_vs_rumore_max` | soglia di «adeguato» (RMSE ≤ valore × σ rumore) | +| `[fit] seed` | seme delle partenze multiple: stessi dati e stessa config danno gli stessi risultati | + +## Test + +```bash +.venv/bin/pytest # tutti +.venv/bin/pytest -k raffreddamento # uno solo +``` +I test verificano, sui seed 1–3, che i domini siano `riposo, riscaldamento, riscaldamento, raffreddamento`, che nel raffreddamento vinca `esp_decad` con τ entro il 10 % di 15.9 s e che il riposo sia `costante`. Richiedono `dati/gen_1.csv`, `gen_2.csv`, `gen_3.csv` (vedi sopra). + +## Codici di uscita + +0 ok · 2 uso errato · 3 configurazione non valida · 4 CSV illeggibile o non valido · 6 domini non validi. + +## Limiti noti + +- Nel raffreddamento i residui sono autocorrelati (ACF1 ≈ 0.7) per scarti casuali e deriva lenta del sensore: i parametri sono buoni, ma gli intervalli di confidenza sono troppo stretti e il dominio risulta «non adeguato». +- I domini di riscaldamento sono corti (2–4 s): il decadimento è quasi lineare e τ non è identificabile; vince un modello semplice, con valore descrittivo e non fisico. +- Ogni dominio è fittato in modo indipendente: nessun vincolo di continuità tra domini. +- Provato su 3 seed; non su file senza gradini o con un solo gradino.