fameio 3.1.0__py3-none-any.whl → 3.2.0__py3-none-any.whl

fameio/scripts/convert_results.py

@@ -1,13 +1,18 @@
 #!/usr/bin/env python
+from __future__ import annotations
+
 import sys
 from pathlib import Path
+from typing import Any, BinaryIO
 
 import pandas as pd
 
+from fameio.cli import update_default_config
 from fameio.cli.convert_results import handle_args, CLI_DEFAULTS as DEFAULT_CONFIG
 from fameio.cli.options import Options
-from fameio.cli import update_default_config
-from fameio.logs import log_critical_and_raise, fameio_logger, log
+from fameio.input import InputError
+from fameio.logs import fameio_logger, log, log_error, log_critical
+from fameio.output import OutputError
 from fameio.output.agent_type import AgentTypeLog
 from fameio.output.conversion import apply_time_option, apply_time_merging
 from fameio.output.csv_writer import CsvWriter
@@ -16,67 +21,154 @@ from fameio.output.input_dao import InputDao
 from fameio.output.output_dao import OutputDAO
 from fameio.output.reader import Reader
 from fameio.output.yaml_writer import data_to_yaml_file
+from fameio.scripts.exception import ScriptError
 
-ERR_MEMORY_ERROR = "Out of memory. Try using `-m` or `--memory-saving` option."
-ERR_MEMORY_SEVERE = "Out of memory despite memory-saving mode. Reduce output interval in `FAME-Core` and rerun model."
+_ERR_OUT_OF_MEMORY = "Out of memory. Retry result conversion using `-m` or `--memory-saving` option."
+_ERR_MEMORY_SEVERE = "Out of memory despite memory-saving mode. Reduce output interval in `FAME-Core` and rerun model."
+_ERR_FILE_OPEN_FAIL = "Could not open file: '{}'"
+_ERR_RECOVER_INPUT = "Could not recover inputs due to an incompatibility with this version of fameio."
+_ERR_FAIL = "Results conversion script failed."
 
+_WARN_OUTPUT_SUPPRESSED = "All output data suppressed by agent filter, but there is data available for agent types: {}"
+_WARN_OUTPUT_MISSING = "Provided file did not contain any output data, only input recovery available."
+_INFO_MEMORY_SAVING = "Memory saving mode enabled: Disable on conversion of small files for performance improvements."
 
-def run(config: dict = None) -> None:
-    """Reads file in protobuf format for configures FILE and extracts its content to .csv file(s)"""
-    config = update_default_config(config, DEFAULT_CONFIG)
-    fameio_logger(log_level_name=config[Options.LOG_LEVEL], file_name=config[Options.LOG_FILE])
 
-    file_path = config[Options.FILE]
-    output_writer = CsvWriter(config[Options.OUTPUT], Path(file_path), config[Options.SINGLE_AGENT_EXPORT])
-    file_stream = open(Path(file_path), "rb")
+def _read_and_extract_data(config: dict[Options, Any]) -> None:
+    """
+    Read protobuf file, extracts, converts, and saves the converted data; Returns false if no result data was found
 
-    if config[Options.MEMORY_SAVING]:
-        log().info("Memory saving mode enabled: Disable on conversion of small files for performance improvements.")
+    Args:
+        config: script configuration options
 
-    log().info("Reading and extracting data...")
-    reader = Reader.get_reader(file=file_stream, read_single=config[Options.MEMORY_SAVING])
-    agent_type_log = AgentTypeLog(requested_agents=config[Options.AGENT_LIST])
-    data_transformer = DataTransformer.build(config[Options.RESOLVE_COMPLEX_FIELD])
+    Raises:
+        OutputError: if file could not be opened or converted, logged with level "ERROR"
+    """
+    file_path = Path(config[Options.FILE])
+    log().info("Opening file for reading...")
     try:
-        input_dao = InputDao()
-        while data_storages := reader.read():
-            if config[Options.INPUT_RECOVERY]:
-                input_dao.store_inputs(data_storages)
-            output = OutputDAO(data_storages, agent_type_log)
-            for agent_name in output.get_sorted_agents_to_extract():
-                log().debug(f"Extracting data for {agent_name}...")
-                data_frames = output.get_agent_data(agent_name, data_transformer)
-                if not config[Options.MEMORY_SAVING]:
-                    apply_time_merging(data_frames, config[Options.TIME_MERGING])
-                    apply_time_option(data_frames, config[Options.TIME])
-                log().debug(f"Writing data for {agent_name}...")
-                output_writer.write_to_files(agent_name, data_frames)
+        with open(file_path, "rb") as file_stream:
+            _extract_and_convert_data(config, file_stream, file_path)
+    except OSError as ex:
+        raise log_error(OutputError(_ERR_FILE_OPEN_FAIL.format(file_path))) from ex
+
 
+def _extract_and_convert_data(config: dict[Options, Any], file_stream: BinaryIO, file_path: Path) -> None:
+    """
+    Extracts data from provided input file stream, converts it, and writes the result to output files
+
+    Args:
+        config: script configuration options
+        file_stream: opened input file
+        file_path: path to input file
+
+    Raises:
+        OutputError: if file could not be opened or converted, logged with level "ERROR"
+    """
+    log().info("Reading and extracting data...")
+    output_writer = CsvWriter(config[Options.OUTPUT], file_path, config[Options.SINGLE_AGENT_EXPORT])
+    agent_type_log = AgentTypeLog(_agent_name_filter_list=config[Options.AGENT_LIST])
+    data_transformer = DataTransformer.build(config[Options.RESOLVE_COMPLEX_FIELD])
+    reader = Reader.get_reader(file=file_stream, read_single=config[Options.MEMORY_SAVING])
+    input_dao = InputDao()
+    while data_storages := reader.read():
         if config[Options.INPUT_RECOVERY]:
-            log().info("Recovering inputs...")
-            timeseries, scenario = input_dao.recover_inputs()
-            base_path = config[Options.OUTPUT] if config[Options.OUTPUT] is not None else "./"
-            series_writer = CsvWriter(Path(base_path, "./recovered"), Path("./"), False)
-            series_writer.write_time_series_to_disk(timeseries)
-            data_to_yaml_file(scenario.to_dict(), Path(base_path, "./recovered/scenario.yaml"))
-
-        if config[Options.MEMORY_SAVING]:
-            written_files = output_writer.pop_all_file_paths()
-            for agent_name, file_path in written_files.items():
-                parsed_data = {None: pd.read_csv(file_path, sep=";", index_col=INDEX)}
-                apply_time_merging(parsed_data, config[Options.TIME_MERGING])
-                apply_time_option(parsed_data, config[Options.TIME])
-                output_writer.write_to_files(agent_name, parsed_data)
-
-        log().info("Data conversion completed.")
-    except MemoryError:
-        log_critical_and_raise(MemoryError(ERR_MEMORY_SEVERE if Options.MEMORY_SAVING else ERR_MEMORY_ERROR))
-
-    file_stream.close()
+            input_dao.store_inputs(data_storages)
+        output = OutputDAO(data_storages, agent_type_log)
+        for agent_name in output.get_sorted_agents_to_extract():
+            log().debug(f"Extracting data for {agent_name}...")
+            data_frames = output.get_agent_data(agent_name, data_transformer)
+            if not config[Options.MEMORY_SAVING]:
+                apply_time_merging(data_frames, config[Options.TIME_MERGING])
+                apply_time_option(data_frames, config[Options.TIME])
+            log().debug(f"Writing data for {agent_name}...")
+            output_writer.write_to_files(agent_name, data_frames)
+
+    if config[Options.INPUT_RECOVERY]:
+        _recover_inputs(config, input_dao)
+    if config[Options.MEMORY_SAVING]:
+        _memory_saving_apply_conversions(config, output_writer)
+
     if not agent_type_log.has_any_agent_type():
-        log().error("Provided file did not contain any output data.")
+        if len(agent_type_log.get_agents_with_output()) > 0:
+            log().warning(_WARN_OUTPUT_SUPPRESSED.format(agent_type_log.get_agents_with_output()))
+        else:
+            log().warning(_WARN_OUTPUT_MISSING)
+    log().info("Data conversion completed.")
+
+
+def _recover_inputs(config: dict[Options, Any], input_dao: InputDao) -> None:
+    """
+    Reads scenario configuration from provided input_dao
+
+    Args:
+        config: script configuration options
+        input_dao: to recover the input data from
+
+    Raises:
+        OutputError: if inputs could not be recovered or saved to files, logged with level "ERROR"
+    """
+    log().info("Recovering inputs...")
+    try:
+        timeseries, scenario = input_dao.recover_inputs()
+    except InputError as ex:
+        raise log_error(OutputError(_ERR_RECOVER_INPUT)) from ex
+    base_path = config[Options.OUTPUT] if config[Options.OUTPUT] is not None else "./"
+    series_writer = CsvWriter(
+        config_output=Path(base_path, "./recovered"), input_file_path=Path("./"), single_export=False
+    )
+    series_writer.write_time_series_to_disk(timeseries)
+    data_to_yaml_file(scenario.to_dict(), Path(base_path, "./recovered/scenario.yaml"))
+
+
+def _memory_saving_apply_conversions(config: dict[Options, Any], output_writer: CsvWriter) -> None:
+    """
+    Rewrite result files in memory saving mode: apply time-merging and time conversion options on a per-file basis
+
+    Args:
+        config: script configuration options
+        output_writer: to rewrite the previously written files
+
+    Raises:
+        OutputError: in case files could not be read, converted, or re-written, logged with level "ERROR"
+    """
+    log().info("Applying time conversion and merging options to extracted files...")
+    written_files = output_writer.pop_all_file_paths()
+    for agent_name, file_path in written_files.items():
+        parsed_data: dict[str | None, pd.DataFrame] = {None: pd.read_csv(file_path, sep=";", index_col=INDEX)}
+        apply_time_merging(parsed_data, config[Options.TIME_MERGING])
+        apply_time_option(parsed_data, config[Options.TIME])
+        output_writer.write_to_files(agent_name, parsed_data)
+
+
+def run(config: dict[Options, Any] | None = None) -> None:
+    """
+    Reads configured file in protobuf format and extracts its content to .CSV and .YAML file(s)
+
+    Args:
+        config: script configuration options
+
+    Raises:
+        ScriptError: if any kind of expected error or a memory error occurred, logged with level "CRITICAL"
+    """
+    config = update_default_config(config, DEFAULT_CONFIG)
+    fameio_logger(log_level_name=config[Options.LOG_LEVEL], file_name=config[Options.LOG_FILE])
+    if config[Options.MEMORY_SAVING]:
+        log().info(_INFO_MEMORY_SAVING)
+
+    try:
+        try:
+            _read_and_extract_data(config)
+        except MemoryError as ex:
+            error = OutputError(_ERR_MEMORY_SEVERE if config[Options.MEMORY_SAVING] else _ERR_OUT_OF_MEMORY)
+            raise log_critical(error) from ex
+    except OutputError as ex:
+        raise log_critical(ScriptError(_ERR_FAIL)) from ex
 
 
 if __name__ == "__main__":
     run_config = handle_args(sys.argv[1:])
-    run(run_config)
+    try:
+        run(run_config)
+    except ScriptError as e:
+        raise SystemExit(1) from e

fameio/scripts/convert_results.py.license

@@ -1,3 +1,3 @@
-SPDX-FileCopyrightText: 2024 German Aerospace Center <fame@dlr.de>
+SPDX-FileCopyrightText: 2025 German Aerospace Center <fame@dlr.de>
 
 SPDX-License-Identifier: Apache-2.0

fameio/scripts/exception.py

@@ -0,0 +1,7 @@
+# SPDX-FileCopyrightText: 2025 German Aerospace Center <fame@dlr.de>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+
+class ScriptError(Exception):
+    """Any kind of expected error that occurred during execution of FAME-Io scripts"""

fameio/scripts/make_config.py

@@ -1,34 +1,56 @@
 #!/usr/bin/env python
+from __future__ import annotations
+
 import sys
 from pathlib import Path
+from typing import Any
 
+from fameio.cli import update_default_config
 from fameio.cli.make_config import handle_args, CLI_DEFAULTS as DEFAULT_CONFIG
 from fameio.cli.options import Options
-from fameio.cli import update_default_config
+from fameio.input import InputError
 from fameio.input.loader import load_yaml, validate_yaml_file_suffix
-from fameio.logs import fameio_logger, log
 from fameio.input.scenario import Scenario
 from fameio.input.validator import SchemaValidator
 from fameio.input.writer import ProtoWriter
+from fameio.logs import fameio_logger, log, log_critical
+from fameio.scripts.exception import ScriptError
+
+_ERR_FAIL: str = "Creation of run configuration file failed."
+
+
+def run(config: dict[Options, Any] | None = None) -> None:
+    """
+    Executes the main workflow of building a FAME configuration file
 
+    Args:
+        config: configuration options
 
-def run(config: dict = None) -> None:
-    """Executes the main workflow for the building of a FAME configuration file"""
+    Raises:
+        ScriptError: if any kind of expected error occurred, logged with level "CRITICAL"
+    """
     config = update_default_config(config, DEFAULT_CONFIG)
     fameio_logger(log_level_name=config[Options.LOG_LEVEL], file_name=config[Options.LOG_FILE])
 
-    file = config[Options.FILE]
-    validate_yaml_file_suffix(Path(file))
-    scenario = Scenario.from_dict(load_yaml(Path(file), encoding=config[Options.INPUT_ENCODING]))
-    SchemaValidator.check_agents_have_contracts(scenario)
+    try:
+        file = config[Options.FILE]
+        validate_yaml_file_suffix(Path(file))
+        scenario_definition = load_yaml(Path(file), encoding=config[Options.INPUT_ENCODING])
+        scenario = Scenario.from_dict(scenario_definition)
+        SchemaValidator.check_agents_have_contracts(scenario)
 
-    timeseries_manager = SchemaValidator.validate_scenario_and_timeseries(scenario)
-    writer = ProtoWriter(config[Options.OUTPUT], timeseries_manager)
-    writer.write_validated_scenario(scenario)
+        timeseries_manager = SchemaValidator.validate_scenario_and_timeseries(scenario)
+        writer = ProtoWriter(config[Options.OUTPUT], timeseries_manager)
+        writer.write_validated_scenario(scenario)
+    except InputError as ex:
+        raise log_critical(ScriptError(_ERR_FAIL)) from ex
 
     log().info("Configuration completed.")
 
 
 if __name__ == "__main__":
     run_config = handle_args(sys.argv[1:])
-    run(run_config)
+    try:
+        run(run_config)
+    except ScriptError as e:
+        raise SystemExit(1) from e

fameio/scripts/make_config.py.license

@@ -1,3 +1,3 @@
-SPDX-FileCopyrightText: 2024 German Aerospace Center <fame@dlr.de>
+SPDX-FileCopyrightText: 2025 German Aerospace Center <fame@dlr.de>
 
 SPDX-License-Identifier: Apache-2.0

fameio/series.py

@@ -1,26 +1,31 @@
-# SPDX-FileCopyrightText: 2023 German Aerospace Center <fame@dlr.de>
+# SPDX-FileCopyrightText: 2025 German Aerospace Center <fame@dlr.de>
 #
 # SPDX-License-Identifier: Apache-2.0
+from __future__ import annotations
+
 import math
 import os
 from enum import Enum, auto
 from pathlib import Path
-from typing import Union, Any
+from typing import Any
 
 import pandas as pd
 from fameprotobuf.input_file_pb2 import InputData
 from google.protobuf.internal.wire_format import INT64_MIN, INT64_MAX
 
+from fameio.input import InputError
 from fameio.input.resolver import PathResolver
-from fameio.logs import log_error_and_raise, log
+from fameio.logs import log, log_error
+from fameio.output import OutputError
 from fameio.time import ConversionError, FameTime
 from fameio.tools import clean_up_file_name
 
+CSV_FILE_SUFFIX = ".csv"
+FILE_LENGTH_WARN_LIMIT = int(50e3)
 
-class TimeSeriesError(Exception):
-    """Indicates that an error occurred during management of time series"""
 
-    pass
+class TimeSeriesError(InputError, OutputError):
+    """Indicates that an error occurred during management of time series"""
 
 
 class Entry(Enum):
@@ -40,19 +45,25 @@ class TimeSeriesManager:
     _ERR_FILE_NOT_FOUND = "Cannot find Timeseries file '{}'."
     _ERR_NUMERIC_STRING = " Remove quotes to use a constant numeric value instead of a timeseries file."
     _ERR_CORRUPT_TIME_SERIES_KEY = "TimeSeries file '{}' corrupt: At least one entry in first column isn't a timestamp."
-    _ERR_CORRUPT_TIME_SERIES_VALUE = "TimeSeries file '{}' corrupt: At least one entry in value column isn't numeric."
+    _ERR_CORRUPT_TIME_SERIES_VALUE = "TimeSeries file '{}' corrupt: At least one entry in second column isn't numeric."
     _ERR_NON_NUMERIC = "Values in TimeSeries must be numeric but was: '{}'"
     _ERR_NAN_VALUE = "Values in TimeSeries must not be missing or NaN."
     _ERR_UNREGISTERED_SERIES = "No timeseries registered with identifier '{}' - was the Scenario validated?"
+    _ERR_UNREGISTERED_SERIES_RE = "No timeseries registered with identifier '{}' - were the timeseries reconstructed?"
     _WARN_NO_DATA = "No timeseries stored in timeseries manager. Double check if you expected timeseries."
     _WARN_DATA_IGNORED = "Timeseries contains additional columns with data which will be ignored."
+    _WARN_LARGE_CONVERSION = (
+        "Timeseries file '{}' is large and needs conversion of time stamps. If performance "
+        "issues occur and the file is reused, convert the time stamp column once with "
+        "`fameio.time.FameTime.convert_datetime_to_fame_time_step(datetime_string)`."
+    )
 
     def __init__(self, path_resolver: PathResolver = PathResolver()) -> None:
         self._path_resolver = path_resolver
         self._id_count = -1
-        self._series_by_id: dict[Union[str, int, float], dict[Entry, Any]] = {}
+        self._series_by_id: dict[str | int | float, dict[Entry, Any]] = {}
 
-    def register_and_validate(self, identifier: Union[str, int, float]) -> None:
+    def register_and_validate(self, identifier: str | int | float) -> None:
         """
         Registers given timeseries `identifier` and validates associated timeseries
 
@@ -60,61 +71,112 @@ class TimeSeriesManager:
             identifier: to be registered - either a single numeric value or a string pointing to a timeseries file
 
         Raises:
-            TimeSeriesException: if file was not found, ill-formatted, or value was invalid
+            TimeSeriesError: if the file could not be found or contains improper data, or if identifier is NaN,
+                logged with level "ERROR"
         """
         if not self._time_series_is_registered(identifier):
             self._register_time_series(identifier)
 
-    def _time_series_is_registered(self, identifier: Union[str, int, float]) -> bool:
+    def _time_series_is_registered(self, identifier: str | int | float) -> bool:
         """Returns True if the value was already registered"""
-        return identifier in self._series_by_id.keys()
+        return identifier in self._series_by_id
+
+    def _register_time_series(self, identifier: str | int | float) -> None:
+        """
+        Assigns an id to the given `identifier` and loads the time series into a dataframe
+
+        Args:
+            identifier: to be registered - either a single numeric value or a string pointing to a timeseries file
 
-    def _register_time_series(self, identifier: Union[str, int, float]) -> None:
-        """Assigns an id to the given `identifier` and loads the time series into a dataframe"""
+        Raises:
+            TimeSeriesError: if the file could not be found or contains improper data, or if identifier is NaN,
+                logged with level "ERROR"
+        """
         self._id_count += 1
         name, series = self._get_name_and_dataframe(identifier)
         self._series_by_id[identifier] = {Entry.ID: self._id_count, Entry.NAME: name, Entry.DATA: series}
 
-    def _get_name_and_dataframe(self, identifier: Union[str, int, float]) -> tuple[str, pd.DataFrame]:
-        """Returns name and DataFrame containing the series obtained from the given `identifier`"""
+    def _get_name_and_dataframe(self, identifier: str | int | float) -> tuple[str, pd.DataFrame]:
+        """
+        Returns name and DataFrame containing the series obtained from the given `identifier`
+
+        Args:
+            identifier: to be registered - either a single numeric value or a string pointing to a timeseries file
+
+        Returns:
+            tuple of name & dataframe
+
+        Raises:
+            TimeSeriesError: if the file could not be found or contains improper data, or if identifier is NaN,
+                logged with level "ERROR"
+        """
         if isinstance(identifier, str):
             series_path = self._path_resolver.resolve_series_file_path(Path(identifier).as_posix())
             if series_path and os.path.exists(series_path):
-                data = pd.read_csv(series_path, sep=";", header=None, comment="#")
                 try:
-                    return identifier, self._check_and_convert_series(data)
+                    data = pd.read_csv(series_path, sep=";", header=None, comment="#")
+                except OSError as e:
+                    raise log_error(TimeSeriesError(e)) from e
+                try:
+                    return identifier, self._check_and_convert_series(data, identifier)
                 except TypeError as e:
-                    log_error_and_raise(TimeSeriesError(self._ERR_CORRUPT_TIME_SERIES_VALUE.format(identifier), e))
-                except ConversionError:
-                    log_error_and_raise(TimeSeriesError(self._ERR_CORRUPT_TIME_SERIES_KEY.format(identifier)))
+                    raise log_error(TimeSeriesError(self._ERR_CORRUPT_TIME_SERIES_VALUE.format(identifier), e)) from e
+                except ConversionError as e:
+                    raise log_error(TimeSeriesError(self._ERR_CORRUPT_TIME_SERIES_KEY.format(identifier), e)) from e
             else:
                 message = self._ERR_FILE_NOT_FOUND.format(identifier)
                 if self._is_number_string(identifier):
                     message += self._ERR_NUMERIC_STRING
-                log_error_and_raise(TimeSeriesError(message))
+                raise log_error(TimeSeriesError(message))
         else:
             return self._create_timeseries_from_value(identifier)
 
-    def _check_and_convert_series(self, data: pd.DataFrame) -> pd.DataFrame:
-        """Ensures validity of time series and convert to required format for writing to disk"""
-        additional_columns = data.loc[:, 2:]
-        is_empty = additional_columns.dropna(how="all").empty
-        if not is_empty:
+    def _check_and_convert_series(self, data: pd.DataFrame, identifier: str) -> pd.DataFrame:
+        """
+        Ensures validity of time series and convert to required format for writing to disk
+
+        Args:
+            data: dataframe to be converted to expected format
+
+        Returns:
+            2-column dataframe, first column: integers, second column: floats (no NaN)
+
+        Raises:
+            ConversionError: if first data column could not be converted to integer, logged with level "ERROR"
+            TypeError: if second data column in given data could not be converted to float or contained NaN,
+                logged with level "ERROR"
+        """
+        data, additional_columns = data.loc[:, :2], data.loc[:, 2:]
+        if not additional_columns.dropna(how="all").empty:
             log().warning(self._WARN_DATA_IGNORED)
         if data.dtypes[0] != "int64":
+            if len(data[0]) > FILE_LENGTH_WARN_LIMIT:
+                log().warning(self._WARN_LARGE_CONVERSION.format(identifier))
             data[0] = [FameTime.convert_string_if_is_datetime(time) for time in data[0]]
-        data[1] = [TimeSeriesManager._assert_valid(value) for value in data[1]]
+        if data.dtypes[1] != "float64":
+            data[1] = [TimeSeriesManager._assert_float(value) for value in data[1]]
+        if data[1].isna().any():
+            raise log_error(TypeError(TimeSeriesManager._ERR_NAN_VALUE))
         return data
 
     @staticmethod
-    def _assert_valid(value: Any) -> float:
-        """Returns the given `value` if it is a numeric value other than NaN"""
+    def _assert_float(value: Any) -> float:
+        """
+        Converts any given value to a float or raise an Exception
+
+        Args:
+            value: to be converted to float
+
+        Returns:
+            float representation of value
+
+        Raises:
+            TypeError: if given value cannot be converted to float, logged with level "ERROR"
+        """
         try:
             value = float(value)
-        except ValueError:
-            log_error_and_raise(TypeError(TimeSeriesManager._ERR_NON_NUMERIC.format(value)))
-        if math.isnan(value):
-            log_error_and_raise(TypeError(TimeSeriesManager._ERR_NAN_VALUE))
+        except ValueError as e:
+            raise log_error(TypeError(TimeSeriesManager._ERR_NON_NUMERIC.format(value))) from e
         return value
 
     @staticmethod
@@ -127,14 +189,25 @@ class TimeSeriesManager:
             return False
 
     @staticmethod
-    def _create_timeseries_from_value(value: Union[int, float]) -> tuple[str, pd.DataFrame]:
-        """Returns name and dataframe for a new static timeseries created from the given `value`"""
+    def _create_timeseries_from_value(value: int | float) -> tuple[str, pd.DataFrame]:
+        """
+        Returns name and dataframe for a new static timeseries created from the given `value`
+
+        Args:
+            value: the static value of the timeseries to be created
+
+        Returns:
+            tuple of name & dataframe
+
+        Raises:
+            TimeSeriesError: if given value is NaN, logged with level "ERROR"
+        """
         if math.isnan(value):
-            log_error_and_raise(TimeSeriesError(TimeSeriesManager._ERR_NAN_VALUE))
+            raise log_error(TimeSeriesError(TimeSeriesManager._ERR_NAN_VALUE))
         data = pd.DataFrame({0: [INT64_MIN, INT64_MAX], 1: [value, value]})
         return TimeSeriesManager._CONSTANT_IDENTIFIER.format(value), data
 
-    def get_series_id_by_identifier(self, identifier: Union[str, int, float]) -> int:
+    def get_series_id_by_identifier(self, identifier: str | int | float) -> int:
         """
         Returns id for a previously stored time series by given `identifier`
 
@@ -145,11 +218,11 @@ class TimeSeriesManager:
             unique ID for the given identifier
 
         Raises:
-            TimeSeriesException: if identifier was not yet registered
+            TimeSeriesError: if identifier was not yet registered, logged with level "ERROR"
         """
         if not self._time_series_is_registered(identifier):
-            log_error_and_raise(TimeSeriesError(self._ERR_UNREGISTERED_SERIES.format(identifier)))
-        return self._series_by_id.get(identifier)[Entry.ID]
+            raise log_error(TimeSeriesError(self._ERR_UNREGISTERED_SERIES.format(identifier)))
+        return self._series_by_id.get(identifier)[Entry.ID]  # type: ignore[index]
 
     def get_all_series(self) -> list[tuple[int, str, pd.DataFrame]]:
         """Returns iterator over id, name and dataframe of all stored series"""
@@ -174,16 +247,28 @@ class TimeSeriesManager:
                 )
             self._series_by_id[one_series.series_id] = reconstructed
 
-    def _get_cleaned_file_name(self, timeseries_name: str):
-        if timeseries_name.lower().endswith(".csv"):
+    def _get_cleaned_file_name(self, timeseries_name: str) -> str:
+        """Ensure given file name has CSV file ending"""
+        if Path(timeseries_name).suffix.lower() == CSV_FILE_SUFFIX:
             filename = Path(timeseries_name).name
         else:
-            filename = clean_up_file_name(timeseries_name) + ".csv"
+            filename = clean_up_file_name(timeseries_name) + CSV_FILE_SUFFIX
         return str(Path(self._TIMESERIES_RECONSTRUCTION_PATH, filename))
 
     def get_reconstructed_series_by_id(self, series_id: int) -> str:
-        """Return name or path for given `series_id` if series these are identified by their number.
-        Use this only if series were added via `reconstruct_time_series`"""
+        """
+        Return name or path for given `series_id` if series these are identified by their number.
+        Use this only if series were added via `reconstruct_time_series`
+
+        Args:
+            series_id: number of series
+
+        Returns:
+            name or path of time series
+
+        Raises:
+            TimeSeriesError: if series was not registered during `reconstruct_time_series`, logged with level "ERROR"
+        """
         if series_id < 0 or series_id > self._id_count:
-            log_error_and_raise(TimeSeriesError(self._ERR_UNREGISTERED_SERIES.format(series_id)))
+            raise log_error(TimeSeriesError(self._ERR_UNREGISTERED_SERIES_RE.format(series_id)))
         return self._series_by_id[series_id][Entry.NAME]