parasolpy 0.0.1__py3-none-any.whl

parasolpy/__init__.py

@@ -0,0 +1,127 @@
+"""Top-level package exports for parasolpy.
+
+Importing names here lets callers write:
+	from parasolpy import has_superheader
+instead of the longer:
+	from parasolpy.file_processing import has_superheader
+
+Both styles always work — the short form is just a convenience. The long
+form (importing directly from the submodule) is never broken by anything here:
+	from parasolpy.tradeoff import append_Kmeans   # always valid
+	from parasolpy import append_Kmeans             # also valid
+"""
+
+__version__ = "0.0.1"
+
+from parasolpy.dash_tools import (
+	build_tradeoff_dash_app,
+	load_dash_inputs,
+)
+from parasolpy.file_processing import (
+	convert_solutions_csv_to_single_header,
+	has_superheader,
+	load_solutions_dataframe,
+	split_solutions_csv,
+	split_solutions_dataframe,
+)
+from parasolpy.interactive import (
+	ExitInteractiveSession,
+	load_experiment_epsilons,
+	prompt_epsilons,
+	prompt_experiment_name,
+	prompt_starting_epsilons,
+)
+from parasolpy.ism import create_ism_traces
+from parasolpy.nowak import (
+	choose_analog_index,
+	sim_multi_trace,
+	sim_single_year,
+)
+from parasolpy.plotting import (
+	plot_trace_exceedance,
+	plot_trace_fan_chart,
+	plot_trace_heatmap,
+	plot_trace_monthly_seasonality,
+	plot_trace_spaghetti,
+)
+from parasolpy.reservoir import sequent_peak
+from parasolpy.tradeoff import (
+	append_Kmeans,
+	build_radar_figure,
+	df_to_pt,
+	label_eps_nd,
+	load_objective_names,
+	load_objectives_and_solutions,
+	log_eps_experiment,
+	normalize_for_radar,
+	parallel_plot_hp,
+	resolve_solutions_csv,
+	run_eps_experiment,
+)
+from parasolpy.util import (
+	convert_cfs_to_af,
+	convert_cfs_to_cms,
+	convert_cms_to_mcm,
+	ensure_dir,
+	pivot_timeseries_by_year,
+	process_xml,
+	read_xml,
+	script_local_path,
+)
+
+# __all__ controls what is exported when someone does `from parasolpy import *`.
+# It also signals to IDEs and documentation tools which names are part of the
+# intentional public API (as opposed to internal helpers imported for convenience).
+# Names starting with _ are intentionally excluded — they are private implementation details.
+__all__ = [
+	# dash_tools
+	"build_tradeoff_dash_app",
+	"load_dash_inputs",
+	# file_processing
+	"has_superheader",
+	"load_solutions_dataframe",
+	"convert_solutions_csv_to_single_header",
+	"split_solutions_dataframe",
+	"split_solutions_csv",
+	# interactive
+	"ExitInteractiveSession",
+	"load_experiment_epsilons",
+	"prompt_epsilons",
+	"prompt_experiment_name",
+	"prompt_starting_epsilons",
+	# ism
+	"create_ism_traces",
+	# nowak
+	"choose_analog_index",
+	"sim_multi_trace",
+	"sim_single_year",
+	# plotting
+	"plot_trace_exceedance",
+	"plot_trace_fan_chart",
+	"plot_trace_heatmap",
+	"plot_trace_monthly_seasonality",
+	"plot_trace_spaghetti",
+	# reservoir
+	"sequent_peak",
+	# tradeoff
+	"append_Kmeans",
+	"build_radar_figure",
+	"df_to_pt",
+	"label_eps_nd",
+	"load_objective_names",
+	"load_objectives_and_solutions",
+	"log_eps_experiment",
+	"normalize_for_radar",
+	"parallel_plot_hp",
+	"resolve_solutions_csv",
+	"run_eps_experiment",
+	# util
+	"convert_cfs_to_af",
+	"convert_cfs_to_cms",
+	"convert_cms_to_mcm",
+	"ensure_dir",
+	"pivot_timeseries_by_year",
+	"process_xml",
+	"read_xml",
+	"script_local_path",
+]

parasolpy/dash_tools.py

@@ -0,0 +1,57 @@
+import pandas as pd
+import plotly.express as px
+from dash import Dash, Input, Output, dcc, html
+
+from parasolpy.tradeoff import load_objectives_and_solutions
+
+
+def load_dash_inputs(output_folder, config_filename=None, solutions_filename=None):
+    """Load objective names and solutions DataFrame for a tradeoff Dash app."""
+    objective_names, solutions = load_objectives_and_solutions(
+        output_folder,
+        config_filename=config_filename,
+        solutions_filename=solutions_filename,
+        return_paths=False,
+    )
+
+    default_color_column = next((name for name in objective_names if name in solutions.columns), solutions.columns[0])
+    return objective_names, solutions, default_color_column
+
+
+def build_tradeoff_dash_app(solutions,
+                            default_color_column,
+                            title="Tradeoff Explorer",
+                            default_colorscale="viridis"):
+    """Create a Dash app for exploring solution tradeoffs via parallel coordinates."""
+    if not isinstance(solutions, pd.DataFrame):
+        raise TypeError("Input 'solutions' must be a pandas DataFrame.")
+    if solutions.empty:
+        raise ValueError("Input 'solutions' cannot be empty.")
+    if not isinstance(default_color_column, str) or default_color_column not in solutions.columns:
+        raise ValueError("Input 'default_color_column' must be a column name in 'solutions'.")
+
+    colorscales = px.colors.named_colorscales()
+    if default_colorscale not in colorscales:
+        default_colorscale = "viridis"
+
+    app = Dash()
+    app.layout = [
+        html.H1(children=title, style={"textAlign": "center"}),
+        dcc.Dropdown(options=list(solutions.columns), value=default_color_column, id="colorcolumn"),
+        dcc.Dropdown(options=colorscales, value=default_colorscale, id="colorscale"),
+        dcc.Graph(figure={}, id="tradeoff-plot"),
+    ]
+
+    @app.callback(
+        Output("tradeoff-plot", "figure"),
+        Input("colorcolumn", "value"),
+        Input("colorscale", "value"),
+    )
+    def update_graph(colorcolumn, colorscale):
+        return px.parallel_coordinates(
+            solutions,
+            color=colorcolumn,
+            color_continuous_scale=colorscale,
+        )
+
+    return app

parasolpy/file_processing.py

@@ -0,0 +1,355 @@
+"""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.
+"""
+
+from __future__ import annotations
+
+import csv
+from pathlib import Path
+
+import pandas as pd
+
+
+_DECISION_GROUP_NAMES = {
+    "decision variables",
+    "decision variable",
+    "decisions",
+}
+
+_OBJECTIVE_GROUP_NAMES = {
+    "objectives",
+    "objective",
+    "objective functions",
+}
+
+
+def _normalize_text(value):
+    """Normalize header/group labels for case-insensitive matching."""
+    if value is None:
+        return ""
+    return str(value).strip()
+
+
+def _is_number(value):
+    """Return True when a string can be parsed as a finite float."""
+    text = _normalize_text(value)
+    if not text:
+        return False
+    try:
+        float(text)
+        return True
+    except ValueError:
+        return False
+
+
+def _row_is_mostly_numeric(row):
+    """Heuristic check used to distinguish header rows from data rows."""
+    cells = [_normalize_text(cell) for cell in row if _normalize_text(cell) != ""]
+    if not cells:
+        return False
+    numeric_count = sum(_is_number(cell) for cell in cells)
+    return numeric_count / len(cells) >= 0.8
+
+
+def _read_first_rows(csv_path, n_rows=2):
+    """Read the first N rows from a CSV with UTF-8 BOM compatibility."""
+    with open(csv_path, "r", encoding="utf-8-sig", newline="") as handle:
+        reader = csv.reader(handle)
+        rows = []
+        for _ in range(n_rows):
+            try:
+                rows.append(next(reader))
+            except StopIteration:
+                break
+    return rows
+
+
+def has_superheader(csv_path):
+    """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.
+    """
+    path = Path(csv_path)
+    if not path.exists() or not path.is_file():
+        raise FileNotFoundError(f"CSV file not found: {path}")
+
+    rows = _read_first_rows(path, n_rows=2)
+    if len(rows) < 2:
+        return False
+
+    row1 = [_normalize_text(cell) for cell in rows[0]]
+    row2 = [_normalize_text(cell) for cell in rows[1]]
+
+    if _row_is_mostly_numeric(row2):
+        return False
+
+    group_label_set = {
+        "decision variables",
+        "objectives",
+        "metrics",
+    }
+    has_known_group_label = any(cell.lower() in group_label_set for cell in row1)
+
+    first_cell_blank = bool(row1) and row1[0] == ""
+    has_any_group_text = any(cell != "" for cell in row1[1:])
+
+    return has_known_group_label or (first_cell_blank and has_any_group_text)
+
+
+def _flatten_columns_and_groups(columns):
+    """Flatten MultiIndex columns and capture per-column group labels."""
+    flattened = []
+    column_to_group = {}
+    used = {}
+    current_group = None
+
+    for idx, column in enumerate(columns):
+        if isinstance(column, tuple):
+            top = _normalize_text(column[0])
+            bottom = _normalize_text(column[1])
+            if top.lower().startswith("unnamed"):
+                top = ""
+            if bottom.lower().startswith("unnamed"):
+                bottom = ""
+
+            if top:
+                current_group = top
+            group = current_group
+
+            name = bottom or top or f"column_{idx + 1}"
+        else:
+            name = _normalize_text(column) or f"column_{idx + 1}"
+            group = None
+
+        count = used.get(name, 0) + 1
+        used[name] = count
+        unique_name = name if count == 1 else f"{name}__{count}"
+
+        flattened.append(unique_name)
+        column_to_group[unique_name] = group
+
+    return flattened, column_to_group
+
+
+def load_solutions_dataframe(csv_path, superheader="auto", return_metadata=False):
+    """Load a solution CSV and normalize headers for downstream processing.
+
+    Args:
+        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.
+    """
+    path = Path(csv_path)
+    if not path.exists() or not path.is_file():
+        raise FileNotFoundError(f"CSV file not found: {path}")
+
+    if superheader not in {"auto", "yes", "no"}:
+        raise ValueError("Input 'superheader' must be one of: 'auto', 'yes', 'no'.")
+
+    if superheader == "auto":
+        has_multi_header = has_superheader(path)
+    else:
+        has_multi_header = superheader == "yes"
+
+    if has_multi_header:
+        df = pd.read_csv(path, header=[0, 1])
+    else:
+        df = pd.read_csv(path)
+
+    if df.empty:
+        raise ValueError(f"Solutions file is empty: {path}")
+
+    flat_columns, column_to_group = _flatten_columns_and_groups(df.columns)
+    df.columns = flat_columns
+
+    groups_to_columns = {}
+    for column in df.columns:
+        group = column_to_group[column]
+        if group is None:
+            continue
+        groups_to_columns.setdefault(group, []).append(column)
+
+    metadata = {
+        "has_superheader": has_multi_header,
+        "column_to_group": column_to_group,
+        "groups_to_columns": groups_to_columns,
+    }
+
+    if return_metadata:
+        return df, metadata
+    return df
+
+
+def convert_solutions_csv_to_single_header(input_csv, output_csv=None, superheader="auto", index=False):
+    """Convert a solutions CSV to a normalized single-header CSV file.
+
+    Args:
+        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.
+    """
+    input_path = Path(input_csv)
+    if output_csv is None:
+        output_path = input_path.with_name(f"{input_path.stem}.single_header.csv")
+    else:
+        output_path = Path(output_csv)
+
+    solutions = load_solutions_dataframe(input_path, superheader=superheader, return_metadata=False)
+    solutions.to_csv(output_path, index=index)
+    return output_path
+
+
+def split_solutions_dataframe(
+    solutions,
+    metadata=None,
+    decision_columns=None,
+    objective_columns=None,
+    id_columns=("Solution", "Solution ID"),
+    include_id_columns=True,
+):
+    """Split a solutions DataFrame into decision and objective DataFrames.
+
+    Args:
+        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'.
+    """
+    if not isinstance(solutions, pd.DataFrame):
+        raise TypeError("Input 'solutions' must be a pandas DataFrame.")
+
+    if decision_columns is not None:
+        if not isinstance(decision_columns, list) or not all(isinstance(c, str) for c in decision_columns):
+            raise TypeError("Input 'decision_columns' must be a list of strings or None.")
+    if objective_columns is not None:
+        if not isinstance(objective_columns, list) or not all(isinstance(c, str) for c in objective_columns):
+            raise TypeError("Input 'objective_columns' must be a list of strings or None.")
+
+    if decision_columns is None or objective_columns is None:
+        groups_to_columns = {}
+        if metadata is not None:
+            groups_to_columns = metadata.get("groups_to_columns", {})
+
+        if decision_columns is None:
+            decision_columns = []
+            for group, cols in groups_to_columns.items():
+                if _normalize_text(group).lower() in _DECISION_GROUP_NAMES:
+                    decision_columns.extend(cols)
+
+        if objective_columns is None:
+            objective_columns = []
+            for group, cols in groups_to_columns.items():
+                if _normalize_text(group).lower() in _OBJECTIVE_GROUP_NAMES:
+                    objective_columns.extend(cols)
+
+    missing_decision = [c for c in decision_columns if c not in solutions.columns]
+    if missing_decision:
+        raise ValueError(f"Decision columns missing from DataFrame: {missing_decision}")
+
+    missing_objective = [c for c in objective_columns if c not in solutions.columns]
+    if missing_objective:
+        raise ValueError(f"Objective columns missing from DataFrame: {missing_objective}")
+
+    if not decision_columns and not objective_columns:
+        raise ValueError(
+            "Could not infer decision/objective columns. Provide explicit column lists "
+            "or load a CSV with a superheader for automatic grouping."
+        )
+
+    id_cols_present = [c for c in id_columns if c in solutions.columns]
+    prefix = id_cols_present if include_id_columns else []
+
+    decisions_df = solutions[prefix + decision_columns].copy()
+    objectives_df = solutions[prefix + objective_columns].copy()
+
+    return {
+        "decisions": decisions_df,
+        "objectives": objectives_df,
+        "decision_columns": decision_columns,
+        "objective_columns": objective_columns,
+    }
+
+
+def 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,
+):
+    """Split a solutions CSV and write decisions-only and objectives-only CSVs.
+
+    Args:
+        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.
+    """
+    input_path = Path(input_csv)
+    if decisions_csv is None:
+        decisions_path = input_path.with_name(f"{input_path.stem}.decisions.csv")
+    else:
+        decisions_path = Path(decisions_csv)
+
+    if objectives_csv is None:
+        objectives_path = input_path.with_name(f"{input_path.stem}.objectives.csv")
+    else:
+        objectives_path = Path(objectives_csv)
+
+    solutions, metadata = load_solutions_dataframe(
+        input_path,
+        superheader=superheader,
+        return_metadata=True,
+    )
+
+    split = split_solutions_dataframe(
+        solutions,
+        metadata=metadata,
+        decision_columns=decision_columns,
+        objective_columns=objective_columns,
+        id_columns=id_columns,
+        include_id_columns=include_id_columns,
+    )
+
+    split["decisions"].to_csv(decisions_path, index=index)
+    split["objectives"].to_csv(objectives_path, index=index)
+
+    return {
+        "decisions_path": decisions_path,
+        "objectives_path": objectives_path,
+        "decision_columns": split["decision_columns"],
+        "objective_columns": split["objective_columns"],
+    }

parasolpy/interactive.py

@@ -0,0 +1,138 @@
+"""Interactive CLI helpers for epsilon experiment workflows.
+
+These functions handle user prompting and input validation; they contain no
+analysis logic. Import them in scripts that need a terminal-based interface
+for iterating on epsilon non-dominance parameters.
+"""
+
+import json
+from pathlib import Path
+
+
+class ExitInteractiveSession(Exception):
+    """Raised when the user requests to exit an interactive CLI workflow."""
+
+
+def _raise_if_exit_requested(value):
+    """Exit the interactive workflow when the user types a quit command."""
+    if value.lower() in {"q", "quit", "exit"}:
+        raise ExitInteractiveSession()
+
+
+def prompt_experiment_name(prompt_text="\nExperiment name: "):
+    """Prompt the user for a filesystem-safe experiment name.
+
+    Returns:
+        str: A sanitized, non-empty experiment name suitable for use in filenames.
+    """
+    while True:
+        name = input(prompt_text).strip()
+        _raise_if_exit_requested(name)
+        if not name:
+            print("  Name cannot be empty.")
+            continue
+        safe = "".join(c if c.isalnum() or c in "_-" else "_" for c in name)
+        if safe != name:
+            print(f"  Sanitized to: {safe}")
+        return safe
+
+
+def prompt_epsilons(objective_names, current_epsilons):
+    """Prompt for an epsilon value per objective, carrying forward the current value as default.
+
+    Args:
+        objective_names: List of objective name strings shown as labels.
+        current_epsilons: List of current epsilon floats used as defaults.
+
+    Returns:
+        list of float: New epsilon values, one per objective.
+    """
+    if len(objective_names) != len(current_epsilons):
+        raise ValueError(
+            "objective_names and current_epsilons must have the same length."
+        )
+    print("Enter epsilon for each objective (press Enter to keep current value, or 'q' to quit):")
+    new_epsilons = []
+    for name, current in zip(objective_names, current_epsilons):
+        while True:
+            raw = input(f"  {name} [{current}]: ").strip()
+            _raise_if_exit_requested(raw)
+            if raw == "":
+                new_epsilons.append(current)
+                break
+            try:
+                val = float(raw)
+                if val <= 0:
+                    print("  Epsilon must be positive.")
+                    continue
+                new_epsilons.append(val)
+                break
+            except ValueError:
+                print("  Invalid number, try again.")
+    return new_epsilons
+
+
+def load_experiment_epsilons(output_folder, experiment_name, objective_names):
+    """Load epsilon defaults from a saved experiment JSON file.
+
+    Args:
+        output_folder: Folder containing per-experiment JSON files.
+        experiment_name: Experiment suffix used in eps_experiment_<name>.json.
+        objective_names: Ordered list of objectives to align the returned epsilons.
+
+    Returns:
+        list of float: Epsilons ordered to match objective_names.
+    """
+    log_path = Path(output_folder) / f"eps_experiment_{experiment_name}.json"
+    if not log_path.exists():
+        raise FileNotFoundError(f"Experiment file not found: {log_path}")
+
+    with open(log_path, "r", encoding="utf-8") as f:
+        record = json.load(f)
+
+    if not isinstance(record, dict) or "epsilons" not in record:
+        raise ValueError(f"Experiment file is missing an 'epsilons' object: {log_path}")
+
+    epsilon_map = record["epsilons"]
+    missing = [name for name in objective_names if name not in epsilon_map]
+    if missing:
+        raise ValueError(
+            f"Experiment file {log_path.name} is missing epsilon values for: {missing}"
+        )
+
+    return [float(epsilon_map[name]) for name in objective_names]
+
+
+def prompt_starting_epsilons(output_folder, objective_names, default_epsilons):
+    """Optionally seed starting epsilons from a previously saved experiment.
+
+    If no prior experiment is chosen, returns default_epsilons unchanged along
+    with None for the experiment name.
+    """
+    folder = Path(output_folder)
+    available = sorted(
+        path.stem.removeprefix("eps_experiment_")
+        for path in folder.glob("eps_experiment_*.json")
+    )
+    if not available:
+        return default_epsilons, None
+
+    print("Saved epsilon experiments:")
+    print(f"  {', '.join(available)}")
+    if len(available) == 1:
+        prompt = (
+            "Load saved experiment by name"
+            f" (or 'y' to use '{available[0]}')? [Enter to skip]: "
+        )
+    else:
+        prompt = "Load saved experiment by name? [Enter to skip, q to quit]: "
+
+    choice = input(prompt).strip()
+    _raise_if_exit_requested(choice)
+    if not choice:
+        return default_epsilons, None
+
+    if len(available) == 1 and choice.lower() in {"y", "yes"}:
+        choice = available[0]
+
+    return load_experiment_epsilons(folder, choice, objective_names), choice