Implementation

This page describes the internal flow of load_csv and the order in which checks are applied. Unlike Overview, the goal here is not to repeat the parameter list, but to clarify how the function builds and validates the DataFrame.

Execution sequence

The implementation follows a simple and predictable sequence:

1. It immediately checks that missing is one of the supported policies: "error", "drop", or "allow".

2. Calls pd.read_csv(...) with:

   • Path(path) as the file path

   • sep

   • decimal

   • comment

   • skipinitialspace=skip_initial_space

3. If rename_columns is provided, it renames the DataFrame columns.

4. If required_columns is provided, it checks that all required columns are present after any renaming.

5. Applies the missing-value policy:

   • with missing="drop" it returns df.dropna()

   • with missing="error" it checks whether at least one NaN exists and, if so, raises ValueError

   • with missing="allow" it leaves the DataFrame unchanged

6. Returns the final DataFrame.

In compact form, the behavior is equivalent to this scheme:

if missing not in {"error", "drop", "allow"}:
    raise ValueError(...)

df = pd.read_csv(
    Path(path),
    sep=sep,
    decimal=decimal,
    comment=comment,
    skipinitialspace=skip_initial_space,
)

if rename_columns:
    df = df.rename(columns=rename_columns)

if required_columns:
    ...

if missing == "drop":
    return df.dropna()

if missing == "error" and df.isna().any().any():
    raise ValueError(...)

return df

Order of checks

The order of the steps is part of the practical contract of the function.

• path is the only positional parameter: all the others are keyword-only.

• Validation of missing happens before reading the file. If the policy is not supported, the function fails immediately.

• required_columns is checked after rename_columns. This allows you to request columns by their final name, not their original file name.

• comment e skip_initial_space non introducono logica aggiuntiva: sono passthrough controllati verso pandas.read_csv.

• Il controllo dei NaN con missing="error" non avviene durante la lettura, ma sul DataFrame gia caricato.

Questo ordine rende il comportamento facile da prevedere nei notebook e negli script: prima si importa il file, poi si normalizzano i nomi, poi si verifica la struttura, e solo alla fine si decide come trattare i valori mancanti.

Missing-value policy

La gestione dei NaN e esplicita e dipende interamente dal parametro missing.

• missing="error": e il default. Dopo il caricamento, la funzione controlla l’intero DataFrame con df.isna().any().any(). Se trova almeno un valore mancante, solleva ValueError.

• missing="drop": il caricamento non fallisce per la presenza di NaN. Le righe incomplete vengono eliminate con DataFrame.dropna(), e il DataFrame restituito puo quindi avere meno righe del file originale.

• missing="allow": la funzione non rimuove nulla e non solleva errori per i NaN. I valori mancanti restano nel DataFrame e vengono gestiti eventualmente a valle.

Dal punto di vista operativo:

• error e utile quando il file deve essere completo prima di passare alle analisi.

• drop e utile quando si vuole un comportamento conservativo ma non bloccante.

• allow e utile quando la gestione dei dati mancanti viene demandata a passaggi successivi.

Se missing riceve un valore diverso da "error", "drop" o "allow", la funzione solleva subito ValueError senza tentare la lettura del CSV.

Interactions between parameters

Alcune combinazioni di parametri definiscono il comportamento pratico piu importante della funzione.

Renaming and required columns

La rinomina avviene prima del controllo su required_columns. Per esempio, se il file contiene una colonna x e si passa rename_columns={"x": "alfa"}, allora required_columns=["alfa"] e valido. Questo evita di dover ragionare contemporaneamente su nomi originali e nomi finali.

Se dopo la rinomina manca ancora una colonna richiesta, la funzione solleva ValueError con l’elenco delle colonne assenti.

Delimiter and decimal separator

sep e decimal vengono inoltrati direttamente a pandas.read_csv. Questo permette di leggere senza logica extra sia CSV “classici” con , e . sia file con formato piu comune in contesto italiano, ad esempio ; come separatore di colonna e , come separatore decimale.

La funzione non esegue conversioni manuali dei numeri: si appoggia al comportamento standard di pandas.

Explicit comments

Il parametro comment e opzionale e ha comportamento opt-in:

• se comment=None, i caratteri come # restano parte del contenuto testuale

• se comment="#", le righe che iniziano con # vengono trattate come commenti da read_csv

Questo dettaglio e importante per evitare che simboli presenti nei dati vengano interpretati come commenti senza una richiesta esplicita.

Spaces after the delimiter

skip_initial_space=True viene tradotto in skipinitialspace=True nella chiamata a pandas. In pratica, gli spazi immediatamente successivi al separatore vengono ignorati gia in fase di lettura, senza passaggi di pulizia aggiuntivi nel DataFrame.

Commented example

from mespy import load_csv

df = load_csv(
    "data/reference/test_misure.csv",
    rename_columns={"misura_n": "n", "lunghezza_mm": "lunghezza", "sigma_mm": "sigma"},
    required_columns=["n", "lunghezza", "sigma"],
    missing="drop",
)

In questo esempio:

• il file di esempio viene letto direttamente dalla cartella data/reference

• le colonne vengono rinominate subito dopo il caricamento

• il controllo su required_columns verifica i nomi finali n, lunghezza e sigma

• eventuali righe con valori mancanti vengono rimosse prima della restituzione

Il risultato finale e un DataFrame gia pronto per essere passato alle funzioni di analisi e plotting del package.