psr-graf 2.3.0__py3-none-any.whl

psr/graf/__init__.py

@@ -0,0 +1 @@
+from .graf import *  # noqa: F403

psr/graf/graf.py

@@ -0,0 +1,716 @@
+from __future__ import annotations
+
+import csv
+import os
+import struct
+from collections.abc import Iterable, Iterator
+from contextlib import contextmanager
+from typing import Any, BinaryIO, TextIO
+
+__all__ = [
+    "BaseBinReader",
+    "BinReader",
+    "CsvReader",
+    "GrafError",
+    "GrafIOError",
+    "__version__",
+    "load_as_dataframe",
+    "open_bin",
+    "open_csv",
+    "version",
+]
+
+__version__ = "2.3.0"
+
+# Number of bytes in a word (int32, float, ...)
+_WORD = 4
+
+# Check whether pandas' dataframe is available.
+try:
+    import numpy as np
+    import pandas as pd
+
+    _HAS_PANDAS = True
+except ImportError:
+    _HAS_PANDAS = False
+
+
+def version() -> str:
+    return __version__
+
+
+class GrafError(Exception):
+    pass
+
+
+class GrafIOError(GrafError):
+    pass
+
+
+class _GrafReaderBase:
+    BLOCK_TYPE_BLOCK = 0
+    BLOCK_TYPE_HOUR = 1
+    STAGE_TYPE_WEEKLY = 1
+    STAGE_TYPE_MONTHLY = 2
+    STAGE_TYPE_13MONTHLY = 6
+    STAGE_DESCRIPTION = {
+        STAGE_TYPE_WEEKLY: "weekly",
+        STAGE_TYPE_MONTHLY: "monthly",
+        STAGE_TYPE_13MONTHLY: "13 months",
+    }
+    BLOCK_DESCRIPTION = {BLOCK_TYPE_BLOCK: "block", BLOCK_TYPE_HOUR: "hour"}
+
+    def __init__(self) -> None:
+        # string encoding
+        self._encoding = "utf-8"
+        # file references
+        self._name = ""
+        # hdr file data
+        self._case_initial_stage = None
+        self._stages = None
+        self._min_stage = None
+        self._max_stage = None
+        self._scenarios = None
+        self._varies_by_scenario = None
+        self._varies_by_block = None
+        self._hour_or_block = None
+        self._stage_type = None
+        self._initial_year = None
+        self._units = None
+        self._agents = None
+
+    @property
+    def initial_stage(self) -> int:
+        return self._case_initial_stage
+
+    @property
+    def stages(self) -> int:
+        return self._stages
+
+    @property
+    def min_stage(self) -> int:
+        return self._min_stage
+
+    @property
+    def max_stage(self) -> int:
+        return self._max_stage
+
+    @property
+    def scenarios(self) -> int:
+        return self._scenarios
+
+    @property
+    def varies_by_scenario(self) -> int:
+        return self._varies_by_scenario
+
+    @property
+    def varies_by_block(self) -> int:
+        return self._varies_by_block
+
+    @property
+    def hour_or_block(self) -> int:
+        return self._hour_or_block
+
+    @property
+    def stage_type(self) -> int:
+        return self._stage_type
+
+    @property
+    def initial_year(self) -> int:
+        return self._initial_year
+
+    @property
+    def units(self) -> str:
+        return self._units
+
+    @property
+    def agents(self) -> tuple[str, ...]:
+        return self._agents
+
+    @property
+    def name(self) -> str:
+        return self._name
+
+    def open(self, file_path: str | os.PathLike[str], **kwargs: Any) -> None:
+        pass
+
+    def close(self) -> None:
+        pass
+
+    def _check_indexes(self, stage: int, scenario: int, block: int | None = None) -> None:
+        if not self._min_stage <= stage <= self._max_stage:
+            raise IndexError(f"Stage {stage} out of range ({self._min_stage}, {self._max_stage}).")
+
+        if not 1 <= scenario <= self._scenarios:
+            raise IndexError(f"Scenario {scenario} out of range ({self._scenarios}).")
+
+        if block is not None:
+            total_blocks = self.blocks(stage)
+            if not 1 <= block <= total_blocks:
+                raise IndexError(f"Block {block} out of range ({total_blocks} for stage {stage}).")
+
+    def blocks(self, stage: int) -> int:
+        raise NotImplementedError
+
+
+class BaseBinReader(_GrafReaderBase):
+    """
+    SDDP binary data reader class.
+    """
+
+    def __init__(self) -> None:
+        super().__init__()
+        # file references
+        self.__hdr_file_path = ""
+        self.__bin_file_path = ""
+        self._bin_file_handler: BinaryIO | None = None
+        self.__single_bin_mode = False
+        self.__bin_offset = 0
+        # print hdr information
+        self._print_metadata = False
+        # hdr file data
+        self._bin_version = None
+        self._name_length = None
+        self._bin_offsets = None
+
+    def __del__(self) -> None:
+        if self._bin_file_handler is not None:
+            self.close()
+
+    @property
+    def bin_version(self) -> int:
+        return self._bin_version
+
+    @property
+    def name_length(self) -> int:
+        return self._name_length
+
+    def open(self, file_path: str | os.PathLike[str], **kwargs: Any) -> None:
+        """
+        Opens a single binary or HDR and BIN file pairs for reading,
+        when one of then is specified. If a file path without extension is
+        specified, tries to open a pair of .hdr and .bin file.
+        The BIN file stays open during BinReader lifetime.
+
+        Keyword arguments:
+        print_metadata -- Print files metadata to stdout (Default = False).
+        encoding -- encoding to decode strings in binary files
+                    (Default = utf-8).
+
+        Non thread-safe method.
+        """
+        self._encoding = kwargs.get("encoding", "utf-8")
+        self._print_metadata = kwargs.get("print_metadata", False)
+
+        # file paths
+        file_path = os.fspath(file_path)
+        base_path, ext = os.path.splitext(file_path)
+        if ext.lower() in (".hdr", ".bin", ""):
+            self.__hdr_file_path = base_path + ".hdr"
+            self.__bin_file_path = base_path + ".bin"
+        else:
+            self.__hdr_file_path = file_path
+            self.__single_bin_mode = True
+        self._name = os.path.basename(base_path)
+
+        # Check files existence.
+        if not os.path.exists(self.__hdr_file_path):
+            if not self.__single_bin_mode:
+                error_msg = f"HDR file not found: {self.__hdr_file_path}"
+            else:
+                error_msg = f"File not found: {self.__hdr_file_path}"
+            raise FileNotFoundError(error_msg)
+
+        if not self.__single_bin_mode:
+            if not os.path.exists(self.__bin_file_path):
+                error_msg = f"BIN file not found: {self.__bin_file_path}"
+                raise FileNotFoundError(error_msg)
+
+        if not self.__single_bin_mode:
+            # read HDR
+            with open(self.__hdr_file_path, "rb") as hdr_file:
+                self.__read_hdr(hdr_file)
+
+            # read BIN and keep it open
+            self._bin_file_handler = open(self.__bin_file_path, "rb")
+        else:
+            # Read single binary file and keep it open.
+            data_file = open(self.__hdr_file_path, "rb")
+            try:
+                self.__read_hdr(data_file)
+            except BaseException:
+                data_file.close()
+                raise
+            self.__bin_offset = data_file.tell()
+            self._bin_file_handler = data_file
+
+    def close(self) -> None:
+        """Closes the binary file for reading."""
+        if self._bin_file_handler is not None and not self._bin_file_handler.closed:
+            self._bin_file_handler.close()
+
+    def __read_hdr(self, input_stream: BinaryIO) -> None:
+        def unpack_int() -> int:
+            """Unpack 4 bytes as integer from input_stream and move its
+            position by 4 bytes.
+            """
+            return struct.unpack("<i", input_stream.read(_WORD))[0]
+
+        def unpack_str(length: int) -> str:
+            # Unpack variable length string.
+            bytes_value = struct.unpack(f"{length}s", input_stream.read(length))[0]
+            return bytes_value.decode(self._encoding).strip()
+
+        # Record #1
+        seek_curpos = 1  # Seek from current position flag
+        input_stream.seek(_WORD, seek_curpos)
+        self._bin_version = unpack_int()
+        input_stream.seek(_WORD, seek_curpos)
+
+        # Record #2
+        input_stream.seek(_WORD, seek_curpos)
+        self._min_stage = unpack_int()
+        self._max_stage = unpack_int()
+        self._scenarios = unpack_int()
+        agents_count = unpack_int()
+        self._varies_by_scenario = unpack_int()
+        self._varies_by_block = unpack_int()
+        self._hour_or_block = unpack_int()
+        self._stage_type = unpack_int()
+        self._case_initial_stage = unpack_int()
+        self._initial_year = unpack_int()
+        self._units = unpack_str(7)
+        self._name_length = unpack_int()
+        self._stages = self._max_stage - self._min_stage + 1
+
+        if self._varies_by_scenario == 0:
+            self._scenarios = 1
+
+        if self._print_metadata:
+            if not self.__single_bin_mode:
+                print("HDR/BIN graf metadata:")
+            else:
+                print("graf metadata:")
+            print("  Binary file version:", self._bin_version)
+            print("  First stage:", self._min_stage)
+            print("  Number of stages:", self._stages)
+            print("  Number of scenarios:", self._scenarios)
+            print("  Number of agents:", agents_count)
+            print("  Varies per scenario:", self._varies_by_scenario)
+            print("  Varies per block/hour:", self._varies_by_block)
+            print("  Time mapping:", BinReader.BLOCK_DESCRIPTION[self._hour_or_block])
+            print("  Type of stage:", BinReader.STAGE_DESCRIPTION[self._stage_type])
+            print("  Case Initial month/week:", self._case_initial_stage)
+            print("  Case Initial year:", self._initial_year)
+            print("  Units:", self._units)
+            print("  Stored name's length:", self._name_length)
+
+        input_stream.seek(_WORD, seek_curpos)
+
+        # Record #3
+        input_stream.seek(_WORD, seek_curpos)
+
+        self._bin_offsets = [unpack_int() for _ in range(self._stages + 1)]
+
+        input_stream.seek(_WORD, seek_curpos)
+
+        # Agent names
+        _agents = []
+        for _ in range(agents_count):
+            string_length = unpack_int()
+            _agents.append(unpack_str(string_length))
+            # discard unused bytes
+            input_stream.read(_WORD)
+        self._agents = tuple(_agents)
+
+    def _seek(self, i_stage: int, i_scenario: int, i_block: int) -> None:
+        # i_scenario, i_block are 1-based indexes; i_stage is 0-based.
+        index = (
+            self._bin_offsets[i_stage] * self._scenarios
+            + self.blocks(i_stage + self._min_stage) * (i_scenario - 1)
+            + (i_block - 1)
+        ) * len(self._agents)
+
+        offset_from_start = self.__bin_offset + index * _WORD
+        seek_from_start = 0
+        self._bin_file_handler.seek(offset_from_start, seek_from_start)
+
+    def _read_stage(
+        self, stage: int, first_scenario: int, last_scenario: int | None = None
+    ) -> tuple[int, bytes]:
+        """Read the raw values of all blocks of a given stage, from first_scenario
+        to last_scenario (Default = first_scenario). Returns the number of blocks
+        and the values, scenario by scenario and block by block."""
+        if last_scenario is None:
+            last_scenario = first_scenario
+        self._check_indexes(stage, first_scenario)
+        self._check_indexes(stage, last_scenario)
+        self._seek(stage - self._min_stage, first_scenario, 1)
+        blocks = self.blocks(stage)
+        count = (last_scenario - first_scenario + 1) * blocks * len(self._agents)
+        return blocks, self._bin_file_handler.read(count * _WORD)
+
+    def blocks(self, stage: int) -> int:
+        """Number of blocks for a given stage. 1-based stage."""
+        istage = stage - self._min_stage + 1
+        if self._varies_by_block != 0:
+            return self._bin_offsets[istage] - self._bin_offsets[istage - 1]
+        return 1
+
+    def read(self, stage: int, scenario: int, block: int) -> tuple[float, ...]:
+        """
+        Read data of a given stage, scenario, and block. Returns a tuple with
+        values for each agent.
+
+        Raises IndexError if stage, scenario, or block is out of bounds.
+
+        Non thread-safe.
+        """
+        self._check_indexes(stage, scenario, block)
+        self._seek(stage - self._min_stage, scenario, block)
+        agents = len(self._agents)
+        return struct.unpack(f"<{agents}f", self._bin_file_handler.read(agents * _WORD))
+
+    def read_blocks(self, stage: int, scenario: int) -> list[list[float]]:
+        """
+        Read data of a given stage and scenario. Returns a list
+        containing lists with block data, for each agent.
+
+        Raises IndexError if stage or scenario is out of bounds.
+
+        Non thread-safe.
+        """
+        blocks, buffer = self._read_stage(stage, scenario)
+        agents = len(self._agents)
+        all_values = struct.unpack(f"<{blocks * agents}f", buffer)
+        return [list(all_values[i_agent::agents]) for i_agent in range(agents)]
+
+    def read_blocks_as_array(self, stage: int, scenario: int) -> tuple[tuple[float, ...], ...]:
+        """
+        Read data of a given stage and scenario. Returns a tuple with
+        dimensions (blocks, agents).
+
+        Raises IndexError if stage or scenario is out of bounds.
+
+        Non thread-safe.
+        """
+        blocks, buffer = self._read_stage(stage, scenario)
+        agents = len(self._agents)
+        all_values = struct.unpack(f"<{blocks * agents}f", buffer)
+        return tuple(all_values[i : i + agents] for i in range(0, len(all_values), agents))
+
+
+if not _HAS_PANDAS:
+
+    class BinReader(BaseBinReader):
+        pass
+
+else:
+
+    class BinReader(BaseBinReader):
+        """
+        A modified version of the psr.graf.BinReader class with an alternative
+        to the read_blocks method, that avoids some expensive for loops by
+        using numpy to reshape the incoming stream into a 2D array.
+        """
+
+        def read_blocks_as_array(self, stage: int, scenario: int) -> np.ndarray:
+            """
+            Read data of a given stage and scenario. Returns a 2D numpy array
+            with dimensions (blocks, agents).
+
+            Raises IndexError if stage or scenario is out of bounds.
+
+            Author: corypdavis
+            """
+            blocks, buffer = self._read_stage(stage, scenario)
+            values = np.frombuffer(buffer, dtype="<f4").astype(np.float32)
+            return values.reshape((blocks, len(self._agents)))
+
+        def _read_stage_array(
+            self, stage: int, first_scenario: int, last_scenario: int
+        ) -> np.ndarray:
+            """Read the values of a range of scenarios of a given stage. Returns a
+            read-only numpy array with dimensions (scenarios, blocks, agents)."""
+            blocks, buffer = self._read_stage(stage, first_scenario, last_scenario)
+            values = np.frombuffer(buffer, dtype="<f4")
+            return values.reshape((-1, blocks, len(self._agents)))
+
+
+class CsvReader(_GrafReaderBase):
+    def __init__(self) -> None:
+        super().__init__()
+        self.__csv_file_path = ""
+        self.__data = {}
+        self.__max_blocks_per_stage = {}
+
+    def open(self, file_path: str | os.PathLike[str], **kwargs: Any) -> None:
+        """
+        Opens a single csv file for reading.
+        """
+        self._encoding = kwargs.get("encoding", "utf-8")
+        file_path = os.fspath(file_path)
+        self.__csv_file_path = file_path
+        self._name = os.path.basename(self.__csv_file_path)
+
+        # Check file existence.
+        if not os.path.exists(file_path):
+            raise FileNotFoundError(f"CSV file not found: {file_path}")
+
+        with open(self.__csv_file_path, encoding=self._encoding) as csv_file:
+            self._read_header(csv_file)
+            self._read_data(csv_file)
+
+    def _read_header(self, csv_file: TextIO) -> None:
+        csv_reader = csv.reader(csv_file, delimiter=",", quotechar='"')
+        header_line1 = next(csv_reader)
+        header_line2 = next(csv_reader)
+        next(csv_reader)
+        header_line_4 = next(csv_reader)
+
+        self._varies_by_block = int(header_line1[1]) >= 1
+        self._units = header_line1[3].strip()
+        stage_type = int(header_line1[4])
+        self._case_initial_stage = int(header_line1[5])
+        self._initial_year = int(header_line1[6])
+        if stage_type in (
+            self.STAGE_TYPE_WEEKLY,
+            self.STAGE_TYPE_MONTHLY,
+            self.STAGE_TYPE_13MONTHLY,
+        ):
+            self._stage_type = stage_type
+        else:
+            raise ValueError(f"Invalid stage type: {stage_type}")
+
+        self._varies_by_scenario = int(header_line2[1]) == 1
+        self._agents = tuple(agent.strip() for agent in header_line_4[3:])
+        self._stages = 0
+        self._scenarios = 0
+
+    def _read_data(self, csv_file: TextIO) -> None:
+        csv_reader = csv.reader(csv_file, delimiter=",", quotechar='"')
+        self.__data = {}
+        self._max_stage = 0
+        self._min_stage = 999999
+        for line in csv_reader:
+            key = tuple(map(int, line[:3]))
+            values = tuple(map(float, line[3:]))
+            self.__data[key] = values
+            # Update limits
+            stage, scenario, block = key
+            self._max_stage = max(self._max_stage, stage)
+            self._min_stage = min(self._min_stage, stage)
+            self._scenarios = max(self._scenarios, scenario)
+            self.__max_blocks_per_stage[stage] = max(
+                self.__max_blocks_per_stage.get(stage, block), block
+            )
+
+        self._stages = self._max_stage - self._min_stage + 1
+
+        if self._is_hourly_data():
+            self._hour_or_block = self.BLOCK_TYPE_HOUR
+        else:
+            self._hour_or_block = self.BLOCK_TYPE_BLOCK
+
+    def _is_hourly_data(self) -> bool:
+        if self._stage_type == self.STAGE_TYPE_WEEKLY:
+            return all(blocks == 168 for blocks in self.__max_blocks_per_stage.values())
+        if self._stage_type == self.STAGE_TYPE_MONTHLY:
+            for stage, blocks in self.__max_blocks_per_stage.items():
+                if stage in (1, 3, 5, 7, 8, 10, 12):
+                    if blocks != 744:
+                        return False
+                elif stage in (4, 6, 9, 11):
+                    if blocks != 720:
+                        return False
+                else:
+                    if blocks != 672:
+                        return False
+            return True
+
+        return False
+
+    def blocks(self, stage: int) -> int:
+        """Number of blocks for a given stage. 1-based stage."""
+        if self._varies_by_block != 0:
+            return self.__max_blocks_per_stage[stage]
+        return 1
+
+    def read(self, stage: int, scenario: int, block: int) -> tuple[float, ...]:
+        """
+        Read data of a given stage, scenario, and block. Returns a tuple with
+        values for each agent.
+
+        Raises IndexError if stage, scenario, or block is out of bounds.
+
+        Non thread-safe.
+        """
+        self._check_indexes(stage, scenario, block)
+        return self.__data[(stage, scenario, block)]
+
+    def _read_stage_array(self, stage: int, first_scenario: int, last_scenario: int) -> np.ndarray:
+        """Read the values of a range of scenarios of a given stage. Returns a
+        numpy array with dimensions (scenarios, blocks, agents). Requires numpy."""
+        blocks = self.blocks(stage)
+        rows = [
+            self.read(stage, scenario, block)
+            for scenario in range(first_scenario, last_scenario + 1)
+            for block in range(1, blocks + 1)
+        ]
+        return np.array(rows, dtype=np.float64).reshape((-1, blocks, len(self._agents)))
+
+
+@contextmanager
+def open_bin(file_path: str | os.PathLike[str], **kwargs: Any) -> Iterator[BinReader]:
+    """
+    Open SDDP binary files (.hdr and .bin) for reading provided a file path
+    for one of them or a file path without extension. Yields a
+    BinReader object.
+
+    Keyword arguments:
+        print_metadata -- Print files metadata to stdout (Default = False).
+        encoding -- encoding to decode strings in binary files
+                    (Default = utf-8).
+    """
+    obj = BinReader()
+    obj.open(file_path, **kwargs)
+    try:
+        yield obj
+    finally:
+        obj.close()
+
+
+@contextmanager
+def open_csv(file_path: str | os.PathLike[str], **kwargs: Any) -> Iterator[CsvReader]:
+    """
+    Open SDDP csv result files (.csv) for reading provided a file path.
+    Yields a CsvReader object.
+    """
+    obj = CsvReader()
+    obj.open(file_path, **kwargs)
+    try:
+        yield obj
+    finally:
+        obj.close()
+
+
+def _get_agent_index_filter(
+    agents: tuple[str, ...], filter_agents: tuple[str, ...]
+) -> tuple[int, ...]:
+    """Indexes of filter_agents in agents. Names are case insensitive."""
+    if len(filter_agents) == 0:
+        return tuple(range(len(agents)))
+    lower_case_agents = tuple(agent.strip().lower() for agent in agents)
+    agents_index = []
+    for agent in filter_agents:
+        try:
+            agents_index.append(lower_case_agents.index(agent.strip().lower()))
+        except ValueError:
+            raise ValueError(f"Agent {agent!r} not found.") from None
+    return tuple(agents_index)
+
+
+def load_as_dataframe(
+    file_path: str | os.PathLike[str],
+    *,
+    multi_index: bool = True,
+    index_format: str = "default",
+    filter_agents: Iterable[str] = (),
+    filter_stages: Iterable[int] = (),
+    filter_scenarios: Iterable[int] = (),
+    filter_blocks: Iterable[int] = (),
+    **kwargs: Any,
+) -> pd.DataFrame:
+    """
+    Load a SDDP result file (.hdr/.bin pair, single binary, or .csv) into a
+    pandas.DataFrame. Requires pandas.
+
+    Keyword arguments:
+        multi_index -- Use a pandas.MultiIndex for the index columns
+                       (Default = True).
+        index_format -- 'default' (stage, scenario, block or hour) or 'period'
+                        (year, month or week, scenario, block or hour).
+        filter_agents -- Agents to include, case insensitive (Default = all).
+        filter_stages -- Stages to include (Default = all).
+        filter_scenarios -- Scenarios to include (Default = all).
+        filter_blocks -- Blocks to include (Default = all).
+    Other keyword arguments, like encoding, are passed to open_bin or open_csv.
+    """
+    if not _HAS_PANDAS:
+        raise ImportError(
+            "load_as_dataframe requires pandas. Install it with: pip install psr-graf[pandas]"
+        )
+    if index_format not in ("default", "period"):
+        raise ValueError(f"Invalid index_format: {index_format!r}. Expected 'default' or 'period'.")
+
+    filter_agents = tuple(filter_agents)
+    filter_stages = set(filter_stages)
+    filter_scenarios = set(filter_scenarios)
+    filter_blocks = set(filter_blocks)
+
+    _, ext = os.path.splitext(file_path)
+    open_fn = open_csv if ext.lower() == ".csv" else open_bin
+    with open_fn(file_path, **kwargs) as graf_file:
+        agents_index = list(_get_agent_index_filter(graf_file.agents, filter_agents))
+        df_agents = [graf_file.agents[i] for i in agents_index]
+        scenarios = [
+            scenario
+            for scenario in range(1, graf_file.scenarios + 1)
+            if not filter_scenarios or scenario in filter_scenarios
+        ]
+
+        # Read each stage at once, then select its scenarios, blocks, and agents.
+        stage_columns, scenario_columns, block_columns, values = [], [], [], []
+        for stage in range(graf_file.min_stage, graf_file.max_stage + 1):
+            if filter_stages and stage not in filter_stages:
+                continue
+            blocks = [
+                block
+                for block in range(1, graf_file.blocks(stage) + 1)
+                if not filter_blocks or block in filter_blocks
+            ]
+            if not scenarios or not blocks:
+                continue
+            stage_values = graf_file._read_stage_array(stage, scenarios[0], scenarios[-1])
+            selection = np.ix_(
+                np.subtract(scenarios, scenarios[0]), np.subtract(blocks, 1), agents_index
+            )
+            values.append(stage_values[selection].reshape((-1, len(agents_index))))
+            stage_columns.append(np.full(len(scenarios) * len(blocks), stage, dtype=np.int64))
+            scenario_columns.append(np.repeat(np.array(scenarios, dtype=np.int64), len(blocks)))
+            block_columns.append(np.tile(np.array(blocks, dtype=np.int64), len(scenarios)))
+
+        if values:
+            values = np.concatenate(values).astype(np.float64, copy=False)
+            stage_column = np.concatenate(stage_columns)
+            scenario_column = np.concatenate(scenario_columns)
+            block_column = np.concatenate(block_columns)
+        else:
+            values = np.empty((0, len(agents_index)), dtype=np.float64)
+            stage_column = scenario_column = block_column = np.empty(0, dtype=np.int64)
+
+        block_or_hour = BinReader.BLOCK_DESCRIPTION[graf_file.hour_or_block]
+        if index_format == "default":
+            index_columns = ("stage", "scenario", block_or_hour)
+            index_arrays = [stage_column, scenario_column, block_column]
+        else:
+            if graf_file.stage_type == _GrafReaderBase.STAGE_TYPE_MONTHLY:
+                month_or_week = "month"
+                max_periods = 12
+            else:
+                month_or_week = "week"
+                max_periods = 52
+            period = stage_column + graf_file.initial_stage - 2
+            index_columns = ("year", month_or_week, "scenario", block_or_hour)
+            index_arrays = [
+                period // max_periods + graf_file.initial_year,
+                period % max_periods + 1,
+                scenario_column,
+                block_column,
+            ]
+
+    if multi_index:
+        index = pd.MultiIndex.from_arrays(index_arrays, names=index_columns)
+        return pd.DataFrame(values, index=index, columns=df_agents)
+    index_df = pd.DataFrame(dict(zip(index_columns, index_arrays, strict=True)))
+    return pd.concat([index_df, pd.DataFrame(values, columns=df_agents)], axis=1)

psr_graf-2.3.0.dist-info/METADATA

@@ -0,0 +1,336 @@
+Metadata-Version: 2.5
+Name: psr-graf
+Version: 2.3.0
+Summary: Utility module to read PSR SDDP's hdr/bin result file pairs.
+Project-URL: Homepage, https://github.com/psrenergy/pygraf
+Project-URL: Issues, https://github.com/psrenergy/pygraf/issues
+Author-email: PSR <d.parrini@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Topic :: Scientific/Engineering
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: pandas
+Requires-Dist: numpy; extra == 'pandas'
+Requires-Dist: pandas; extra == 'pandas'
+Description-Content-Type: text/markdown
+
+PyGraf
+======
+
+
+Utility module to read SDDP hdr/bin result file pairs. Some [examples](#usage-samples) to convert it to 
+popular formats are available.
+
+
+Installing
+----------
+
+Install the latest version from [PyPI](https://pypi.org/project/psr-graf/)
+
+```
+pip install psr-graf
+```
+
+To use `load_as_dataframe`, install it with the optional `pandas` dependency:
+
+```
+pip install "psr-graf[pandas]"
+```
+
+Or download this repository contents.
+
+
+Usage
+-----
+
+Start by importing `psr.graf` module. It's possible to read data directly using `open_bin` and `open_csv` functions 
+or `load_as_dataframe` function if `pandas` package is available.
+
+
+The example below shows how to load data directly into a `pandas.DataFrame` and prints the first 5 lines of data.
+
+```python
+import psr.graf
+
+df = psr.graf.load_as_dataframe("sample_data/gerter.hdr")
+print(df.head())
+```
+
+The output is:
+```
+                      Thermal 1  Thermal 2  Thermal 3
+stage scenario block                                 
+1     1        1       7.440000      0.744   0.368069
+      2        1       6.437624      0.000   0.000000
+      3        1       7.440000      0.744   0.576140
+      4        1       7.440000      0.744   2.994997
+      5        1       7.440000      0.744   0.916644
+```
+
+Alternatively, `open_bin` and `open_csv` functions can be used for direct data access as shown in the example next.
+
+```python
+import psr.graf
+
+with psr.graf.open_bin("sample_data/gerter.hdr") as graf_file:
+    print("Stages:", graf_file.stages)
+    print("Scenarios:", graf_file.scenarios)
+    print("Agents:", graf_file.agents)
+    print(f"Initial date: {graf_file.initial_year:04d}/{graf_file.initial_stage:02d}")
+    print("Units:", graf_file.units)
+    stage = 2
+    print(f"Number of blocks at stage {stage}: {graf_file.blocks(stage)}")
+    scenario = 10
+    block = 1
+    print(
+        f"Data at stage {stage}, scenario {scenario}, block {block}:",
+        graf_file.read(stage, scenario, block),
+    )
+```
+
+The output is:
+```
+Stages: 12
+Scenarios: 50
+Agents: ('Thermal 1', 'Thermal 2', 'Thermal 3')
+Initial date: 2013/01
+Units: GWh
+Number of blocks at stage 2: 1
+Data at stage 2, scenario 10, block 1: (7.440000057220459, 0.7440000176429749, 0.3680693209171295)
+```
+
+Requirements
+------------
+
+* Python 3.10 or newer.
+* (Optional) `pandas` package to use `load_as_dataframe` function, installed with the `pandas` extra.
+
+
+File Formats
+------------
+
+| File Extension | Description                      |
+|:--------------:|:---------------------------------|
+| .hdr or .bin   | Binary .hdr and .bin pair        |
+| .dat           | Single-binary file               |
+| .csv           | CSV file with specific structure |
+
+* `load_as_dataframe` supports all of them and will determine which reader will be used based on the file extension.
+* `open_bin` supports only .hdr/bin pairs or single-binary files.
+* `open_csv` supports only CSV.
+
+
+Both `open_bin`, `open_csv`, and `load_as_dataframe` functions accept `encoding` parameter to specify the encoding of the strings in file. The default is `utf-8`.
+
+
+DataFrame options
+-----------------
+
+
+### MultiIndex or single index
+
+`load_as_dataframe` accepts an optional keyword argument `multi_index` (default `True`) to specify if the 
+returned `pandas.DataFrame` should use `pandas.MultiIndex` or not. If `False`, the returned `pandas.DataFrame` will have a
+single automatic index and the columns 'stage', 'scenario', 'block' will appear before the agents' data.
+
+Example:
+```python
+import psr.graf
+
+df = psr.graf.load_as_dataframe("sample_data/gerter.hdr", multi_index=False)
+print(df.head())
+print("Column names:", df.columns.values)
+```
+
+The output is:
+```
+   stage  scenario  block  Thermal 1  Thermal 2  Thermal 3
+0      1         1      1   7.440000      0.744   0.368069
+1      1         2      1   6.437624      0.000   0.000000
+2      1         3      1   7.440000      0.744   0.576140
+3      1         4      1   7.440000      0.744   2.994997
+4      1         5      1   7.440000      0.744   0.916644
+Column names: ['stage' 'scenario' 'block' 'Thermal 1' 'Thermal 2' 'Thermal 3']
+```
+
+On the other hand, 
+
+```python
+import psr.graf
+
+df = psr.graf.load_as_dataframe("sample_data/gerter.hdr", multi_index=True)
+print(df.head())
+print("Column names:", df.columns.values)
+```
+
+Will produce the following output:
+```
+                      Thermal 1  Thermal 2  Thermal 3
+stage scenario block                                 
+1     1        1       7.440000      0.744   0.368069
+      2        1       6.437624      0.000   0.000000
+      3        1       7.440000      0.744   0.576140
+      4        1       7.440000      0.744   2.994997
+      5        1       7.440000      0.744   0.916644
+Column names: ['Thermal 1' 'Thermal 2' 'Thermal 3']
+```
+
+### Index formats
+
+The `index_format` specifies the format of index columns of the returned `pandas.Dataframe`. It accepts the following
+values:
+
+| Index Format | Columns                                      |
+|:------------:|:---------------------------------------------|
+|  `default`   | stage, scenario, block or hour               |
+|   `period`   | year, month or week, scenario, block or hour |
+
+* `default` creates a `pandas.DataFrame` with the columns as they are stored in the original file.
+* `period` converts `stage` into `year`, `month` or `week` depending on the stage type of the file and the 
+   initial year and stage.
+
+
+### Filter by stage, scenario, block and/or agent
+
+The `load_as_dataframe` function accepts the following optional keyword arguments to filter data:
+
+|      Argument      | Description                                                                   |
+|:------------------:|:------------------------------------------------------------------------------|
+|  `filter_stages`   | List of stages to be included                                                 |
+|  `filter_blocks`   | List of blocks to be included                                                 |
+| `filter_scenarios` | List of scenarios to be included                                              |
+|  `filter_agents`   | List of agents to be included. The name is case insensitive.                  |
+
+An empty list or unspecified means all stages, blocks, scenarios or agents will be included.
+
+Example:
+```python
+import psr.graf
+
+df = psr.graf.load_as_dataframe(
+    "sample_data/gerter.hdr",
+    filter_stages=[
+        8,
+    ],
+    filter_scenarios=[
+        10,
+    ],
+    filter_agents=["Thermal 3", "Thermal 2"],
+)
+print(df.head())
+```
+
+Outputs:
+```
+                      Thermal 3  Thermal 2
+stage scenario block                      
+8     10       1       8.030441        0.0
+```
+
+
+
+Usage Samples
+-------------
+
+### [`dataframes_sample.py`](https://github.com/psrenergy/pygraf/blob/main/dataframes_sample.py)
+
+Shows how to read data into `pandas.DataFrame`s.
+
+Requires `pandas` package installed.
+
+
+### [`matplotlib_sample.py`](https://github.com/psrenergy/pygraf/blob/main/matplotlib_sample.py)
+
+Shows how to read data and plot data from hdr/bin file pairs.
+
+![](https://raw.githubusercontent.com/psrenergy/pygraf/main/docs/matplotlib_sample_plot.png)
+
+Requires `matplotlib` package installed.
+
+
+
+### [`csv_sample.py`](https://github.com/psrenergy/pygraf/blob/main/csv_sample.py)
+
+Shows how to convert from hdr/bin file pairs to csv using `psr.graf` module.
+
+This script can also be called from command line:
+
+```bat
+python csv_sample.py input_file.hdr output_file.csv
+```
+
+Where `output_file.csv` is optional.
+
+
+### [`parquet_sample.py`](https://github.com/psrenergy/pygraf/blob/main/parquet_sample.py)
+
+Shows how to convert from hdr/bin file pairs to Apache Parquet format.
+
+Requires `pyarrow` package installed.
+
+This script can also be called from command line:
+
+```bat
+python parquet_sample.py input_file.hdr output_file.parquet
+```
+
+Where `output_file.parquet` is optional.
+
+
+
+Development
+-----------
+
+The project uses [uv](https://docs.astral.sh/uv/) for development. To set up an environment with the
+development dependencies, run the tests, and lint and format the code:
+
+```
+uv sync
+uv run pytest
+uv run ruff check
+uv run ruff format
+```
+
+To build the source distribution and wheel into `dist/`:
+
+```
+uv build
+```
+
+
+### Releasing
+
+Update `__version__` in `psr/graf/graf.py`, then push a tag with the same version:
+
+```
+git tag 2.3.0
+git push origin 2.3.0
+```
+
+PyPI never accepts a version that was uploaded before, even after it is deleted, so versions like 2.2.0
+cannot be used again.
+
+The [Publish](.github/workflows/publish.yml) workflow runs the tests, builds the package, and
+uploads it to PyPI using [trusted publishing](https://docs.pypi.org/trusted-publishers/).
+
+
+Issues and Support
+------------------
+
+Check PyGraf's [GitHub repository](https://github.com/psrenergy/pygraf/) and [issues page](https://github.com/psrenergy/pygraf/issues) for support.
+
+
+License
+-------
+
+PyGraf is licensed under the [MIT License](https://github.com/psrenergy/pygraf/blob/main/LICENSE).

psr_graf-2.3.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+psr/graf/__init__.py,sha256=888LVNjnDSeRrCRyMmKzoUH5fdqCu7xPHjS-ev10vDE,34
+psr/graf/graf.py,sha256=yii0D2DAG7hWvJx3lexJJZTw4TrQmsYmRcbXUCd2pqY,25788
+psr/graf/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+psr_graf-2.3.0.dist-info/METADATA,sha256=KvquCR1F5Ulp6dBG7Rw_3rkVq6x_uYbo9UDrvSYdzts,10012
+psr_graf-2.3.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+psr_graf-2.3.0.dist-info/licenses/LICENSE,sha256=EEHshT2r876fXUsEDuEgtvH9bPs0PUbexFqsEujBLRM,1060
+psr_graf-2.3.0.dist-info/RECORD,,

psr_graf-2.3.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

psr_graf-2.3.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 PSR
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.