parasolpy.file_processing

File-processing helpers for Borg/RiverWare solution CSVs.

This module focuses on common post-processing tasks for solution files, including: 1) Normalizing two-line “superheader” CSVs to single-header CSVs. 2) Splitting decision-variable and objective columns for downstream analysis.

Functions

convert_solutions_csv_to_single_header(input_csv)

Convert a solutions CSV to a normalized single-header CSV file.

has_superheader(csv_path)

Detect whether a solutions CSV likely uses a two-line superheader.

load_solutions_dataframe(csv_path[, ...])

Load a solution CSV and normalize headers for downstream processing.

split_solutions_csv(input_csv[, ...])

Split a solutions CSV and write decisions-only and objectives-only CSVs.

split_solutions_dataframe(solutions[, ...])

Split a solutions DataFrame into decision and objective DataFrames.
parasolpy.file_processing.has_superheader(csv_path)[source]

Detect whether a solutions CSV likely uses a two-line superheader.

A superheader file usually has grouped labels on row 1 (for example, “Decision Variables”, “Objectives”) and the actual column names on row 2.

parasolpy.file_processing.load_solutions_dataframe(csv_path, superheader='auto', return_metadata=False)[source]

Load a solution CSV and normalize headers for downstream processing.

Parameters:

  • csv_path – Path to the input CSV.

  • superheader – One of “auto”, “yes”, “no”.

  • return_metadata – If True, also returns a metadata dict with grouped column info.

Returns:

DataFrame, or (DataFrame, metadata) when return_metadata is True.

parasolpy.file_processing.convert_solutions_csv_to_single_header(input_csv, output_csv=None, superheader='auto', index=False)[source]

Convert a solutions CSV to a normalized single-header CSV file.

Parameters:

  • input_csv – Source CSV path.

  • output_csv – Destination path. If None, writes next to input using ‘<stem>.single_header.csv’.

  • superheader – One of “auto”, “yes”, “no”.

  • index – Whether to write DataFrame index to output CSV.

Returns:

pathlib.Path to the written CSV.

parasolpy.file_processing.split_solutions_dataframe(solutions, metadata=None, decision_columns=None, objective_columns=None, id_columns=('Solution', 'Solution ID'), include_id_columns=True)[source]

Split a solutions DataFrame into decision and objective DataFrames.

Parameters:

  • solutions – Input DataFrame.

  • metadata – Metadata returned from load_solutions_dataframe(…, return_metadata=True). Used to auto-detect grouped columns from a superheader.

  • decision_columns – Explicit decision-variable columns. If None, inferred from metadata.

  • objective_columns – Explicit objective columns. If None, inferred from metadata.

  • id_columns – Candidate ID columns to preserve in each output DataFrame.

  • include_id_columns – Whether to keep detected ID columns in outputs.

Returns:

dict with keys ‘decisions’, ‘objectives’, ‘decision_columns’, ‘objective_columns’.

parasolpy.file_processing.split_solutions_csv(input_csv, decisions_csv=None, objectives_csv=None, superheader='auto', decision_columns=None, objective_columns=None, id_columns=('Solution', 'Solution ID'), include_id_columns=True, index=False)[source]

Split a solutions CSV and write decisions-only and objectives-only CSVs.

Parameters:

  • input_csv – Source solutions CSV path.

  • decisions_csv – Destination for decision-variable subset. Defaults to ‘<stem>.decisions.csv’.

  • objectives_csv – Destination for objective subset. Defaults to ‘<stem>.objectives.csv’.

  • superheader – One of “auto”, “yes”, “no”.

  • decision_columns – Explicit decision columns, optional.

  • objective_columns – Explicit objective columns, optional.

  • id_columns – Candidate ID columns to keep.

  • include_id_columns – Include ID columns in both outputs.

  • index – Whether to write DataFrame index to output CSVs.

Returns:

dict with output paths and detected column groupings.