GUIBRUSHR.core.io.retrieval_io module

Typed YAML I/O for retrieval folders.

A retrieval folder lives at Files/Targets/<target>/Retrievals/<run>/ and historically held two CSV files:

  • df_general_info.csv — 2-column Variable/Value key/value table

  • df_parameters.csv — 15-column DataFrame, one row per fitted parameter

Both files round-tripped via pandas.DataFrame.to_csv()/read_csv lose all dtype information: every value comes back as object. This module replaces that with typed YAML persistence while keeping legacy CSVs readable through a lazy conversion path. Writes go through atomic temp + os.replace so a mid-write crash never leaves a partial file.

Public API

  • read_general_info(folder)() -> typed dict

  • read_general_info_df(folder)() -> 2-col legacy-shaped DataFrame

  • write_general_info(folder, data)() -> Path (accepts dict or DF)

  • read_parameters(folder)() -> 15-col DataFrame, NaN preserved

  • write_parameters(folder, df)() -> Path

  • ensure_yaml(folder)() -> {"general_info": Path, "parameters": Path}

  • RetrievalIOError

The CSV is never deleted or renamed by this module.

exception GUIBRUSHR.core.io.retrieval_io.RetrievalIOError[source]

Bases: Exception

Raised on retrieval-folder I/O errors (empty YAML, missing file, schema mismatch).

GUIBRUSHR.core.io.retrieval_io.read_general_info(folder: str | PathLike) → Dict[str, Any][source]

Return the general-info table as a typed dict.

Prefers df_general_info.yaml; falls back to legacy CSV and lazily writes a YAML sibling so subsequent reads are fast. The CSV is never deleted or modified.

Raises RetrievalIOError if neither file exists or the YAML is empty.

GUIBRUSHR.core.io.retrieval_io.read_general_info_df(folder: str | PathLike) → DataFrame[source]

Return the general-info table as a 2-col legacy-shaped DataFrame.

Used by call sites that pass the result to get_csv_value(). List values are kept as native Python lists in the Value column (object dtype).

GUIBRUSHR.core.io.retrieval_io.write_general_info(folder: str | PathLike, data: Mapping[str, Any] | DataFrame) → Path[source]

Write df_general_info.yaml with typed values. Accepts dict or 2-col DF.

GUIBRUSHR.core.io.retrieval_io.read_parameters(folder: str | PathLike) → DataFrame[source]

Return the 15-col parameters DataFrame, NaN preserved for missing cells.

GUIBRUSHR.core.io.retrieval_io.write_parameters(folder: str | PathLike, df: DataFrame) → Path[source]

Write df_parameters.yaml. NaN cells are omitted from the YAML.

GUIBRUSHR.core.io.retrieval_io.ensure_yaml(folder: str | PathLike) → Dict[str, Path][source]

Ensure YAML siblings exist for any legacy CSV in folder.

Returns a mapping {"general_info": <path>, "parameters": <path>} for each kind that exists (in either format). The CSV is left untouched. Calling twice is a no-op (idempotent).