my-lib-lunati 0.1.2
Una libreria Python per l'analisi dati con fit lineari e test statistici.
Requires Python: >=3.8
Keywords: fit, analisi dati, chi quadro, statistica, scienza, regressione lineare, minimi quadrati


---

# my-lib-lunati

[![PyPI version](https://badge.fury.io/py/my-lib-lunati.svg)](https://badge.fury.io/py/my-lib-lunati)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

Una libreria Python leggera e focalizzata per le operazioni comuni di analisi dati in contesti scientifici e sperimentali. Esegui fit lineari pesati e non, calcola la bontà del fit con il Chi Quadro e confronta misure in modo statisticamente robusto con un'API semplice e intuitiva.

Questa libreria è stata creata per essere uno strumento pratico e di facile utilizzo, ideale per l'analisi rapida di dati in ambienti come Jupyter Notebooks, Google Colab o script personali.

## Caratteristiche Principali

*   **Fit Lineari Multipli**:
    *   **Pesato**: Ideale quando si conoscono le incertezze su ogni punto dati (`calcola_fit_lineare_pesato`).
    *   **Semplice**: Utile quando le incertezze non sono note e vengono stimate dalla dispersione dei dati (`calcola_fit_lineare_semplice`).
    *   **Bayesiano**: Fornisce un'analisi completa della posterior probability per i parametri del fit (`calcola_fit_bayesiano`).
*   **Valutazione della Bontà del Fit**:
    *   Calcola il **Chi Quadro ($\chi^2$)**, i gradi di libertà, il Chi Quadro ridotto e il p-value per determinare quantitativamente la qualità del fit (`calcola_chi_quadro`).
*   **Test Statistici**:
    *   **Test di Compatibilità**: Confronta due misure sperimentali (es. un valore misurato e uno teorico) e ne calcola la compatibilità tramite z-score (`test_compatibilita`).
*   **Funzioni Helper**:
    *   Stampa i risultati in tabelle formattate e di facile lettura.

## Installazione

Puoi installare `my-lib-lunati` direttamente da PyPI usando `pip`. È consigliabile farlo all'interno di un ambiente virtuale.

```bash
pip install my-lib-lunati
```

La libreria dipende da `numpy` e `scipy`, che verranno installati automaticamente se non già presenti.

## Guida Rapida (Quickstart)

Ecco un esempio completo che mostra un tipico flusso di lavoro in meno di 20 righe di codice.

```python
import numpy as np
import my_lib_lunati as mll

# --- 1. Dati Sperimentali di Esempio ---
# Immaginiamo di aver misurato la relazione tra due variabili
x_data = np.array([1, 2, 3, 4, 5, 6, 7, 8])
y_data = np.array([3.4, 5.6, 7.9, 10.1, 12.4, 14.6, 17.0, 18.9])
y_error = np.array([0.4, 0.5, 0.4, 0.6, 0.5, 0.5, 0.6, 0.7])


# --- 2. Eseguire il Fit Lineare Pesato ---
# Usiamo il fit pesato perché conosciamo gli errori sui punti y
risultati_fit = mll.calcola_fit_lineare_pesato(x_data, y_data, y_error)


# --- 3. Stampare i Risultati del Fit ---
# La funzione helper formatta l'output in modo chiaro
mll.stampa_risultati_fit(risultati_fit, titolo="--- Fit Lineare dei Dati Sperimentali ---")


# --- 4. Valutare la Bontà del Fit (Test del Chi Quadro) ---
# Prima calcoliamo i valori y predetti dal nostro modello
m_fit = risultati_fit['pendenza']
q_fit = risultati_fit['intercetta']
y_predetti = m_fit * x_data + q_fit

# Ora eseguiamo il test del Chi Quadro (2 parametri liberi: m e q)
risultati_chi2 = mll.calcola_chi_quadro(y_data, y_predetti, y_error, num_parametri_fit=2)
mll.stampa_chi_quadro(risultati_chi2)
```

**Output dell'esempio:**

```
--- Fit Lineare dei Dati Sperimentali ---
Pendenza (m)      = 2.531061 ± 0.128863
Intercetta (q)    = 0.9413 ± 0.6380
Covarianza (m,q)   = -0.077382
========================================

--- TEST DI BONTÀ DEL FIT (CHI QUADRO) ---
Chi Quadro (χ²)               : 5.861
Gradi di Libertà (dof)        : 6
Chi Quadro Ridotto (χ²/dof)   : 0.977
p-value                       : 0.4390

Interpretazione: Chi^2 ridotto ≈ 1. Modello e dati sono compatibili.
=============================================
```

## Documentazione e API

La libreria è documentata direttamente nel codice tramite docstring dettagliate. Per ottenere informazioni su qualsiasi funzione, i suoi parametri e i valori restituiti, usa la funzione `help()` nell'interprete Python:

```python
import my_lib_lunati as mll

# Ottieni aiuto sulla funzione del fit pesato
help(mll.calcola_fit_lineare_pesato)

# Ottieni aiuto sulla funzione del Chi Quadro
help(mll.calcola_chi_quadro)
```

## Contribuire

Le contribuzioni sono benvenute! Se trovi un bug o hai un'idea per una nuova funzionalità, per favore apri una "Issue" sulla pagina GitHub del progetto.

## Licenza

Questo progetto è rilasciato sotto la Licenza MIT. Vedi il file `LICENSE` per maggiori dettagli.

---