my-lib-lunati 0.1.0

Una libreria Python per l'analisi dati con fit lineari e test statistici.

---

my-lib-lunati

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.

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.

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:

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.

---