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

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,30 @@
 # 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, 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):
+class TimeSeriesError(InputError, OutputError):
     """Indicates that an error occurred during management of time series"""
 
 
@@ -41,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
 
@@ -61,29 +71,54 @@ 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
 
-    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"""
+    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
+
+        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:
                     raise log_error(TimeSeriesError(self._ERR_CORRUPT_TIME_SERIES_VALUE.format(identifier), e)) from e
                 except ConversionError as e:
@@ -96,26 +131,52 @@ class TimeSeriesManager:
         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 as e:
             raise log_error(TypeError(TimeSeriesManager._ERR_NON_NUMERIC.format(value))) from e
-        if math.isnan(value):
-            raise log_error(TypeError(TimeSeriesManager._ERR_NAN_VALUE))
         return value
 
     @staticmethod
@@ -128,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):
             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`
 
@@ -146,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):
             raise log_error(TimeSeriesError(self._ERR_UNREGISTERED_SERIES.format(identifier)))
-        return self._series_by_id.get(identifier)[Entry.ID]
+        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"""
@@ -175,7 +247,8 @@ class TimeSeriesManager:
                 )
             self._series_by_id[one_series.series_id] = reconstructed
 
-    def _get_cleaned_file_name(self, timeseries_name: str):
+    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:
@@ -183,8 +256,19 @@ class TimeSeriesManager:
         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:
-            raise log_error(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]

fameio/time.py

@@ -1,13 +1,17 @@
 # SPDX-FileCopyrightText: 2025 German Aerospace Center <fame@dlr.de>
 #
 # SPDX-License-Identifier: Apache-2.0
+from __future__ import annotations
+
 import datetime as dt
 import math
 import re
 from enum import Enum, auto
-from typing import Union
+from typing import Any
 
+from fameio.input import InputError
 from fameio.logs import log_error
+from fameio.output import OutputError
 
 START_IN_REAL_TIME = "2000-01-01_00:00:00"
 DATE_FORMAT = "%Y-%m-%d_%H:%M:%S"
@@ -15,8 +19,8 @@ DATE_REGEX = re.compile("[0-9]{4}-[0-9]{2}-[0-9]{2}_[0-9]{2}:[0-9]{2}:[0-9]{2}")
 FAME_FIRST_DATETIME = dt.datetime.strptime(START_IN_REAL_TIME, DATE_FORMAT)
 
 
-class ConversionError(Exception):
-    """Indicates that something went wrong during time stamp conversion"""
+class ConversionError(InputError, OutputError):
+    """Indicates that time stamp conversion failed"""
 
 
 class TimeUnit(Enum):
@@ -45,9 +49,9 @@ class Constants:
     STEPS_PER_DAY = STEPS_PER_HOUR * HOURS_PER_DAY
     STEPS_PER_YEAR = STEPS_PER_DAY * DAYS_PER_YEAR
     STEPS_PER_WEEK = STEPS_PER_DAY * 7
-    STEPS_PER_MONTH = STEPS_PER_YEAR / 12
+    STEPS_PER_MONTH = int(STEPS_PER_YEAR / 12)
 
-    steps_per_unit = {
+    steps_per_unit: dict[TimeUnit, int] = {
         TimeUnit.SECONDS: STEPS_PER_SECOND,
         TimeUnit.MINUTES: STEPS_PER_MINUTE,
         TimeUnit.HOURS: STEPS_PER_HOUR,
@@ -70,7 +74,19 @@ class FameTime:
 
     @staticmethod
     def convert_datetime_to_fame_time_step(datetime_string: str) -> int:
-        """Converts real Datetime string to FAME time step"""
+        """
+        Converts Datetime string to FAME time step
+
+        Args:
+            datetime_string: a datetime in FAME formatting
+
+        Returns:
+            corresponding FAME time step
+
+        Raises:
+            ConversionError: if string could not be interpreted or does not represent a valid FAME time step,
+                logged with level "ERROR"
+        """
         if not FameTime.is_datetime(datetime_string):
             raise log_error(ConversionError(FameTime._FORMAT_INVALID.format(datetime_string)))
         datetime = FameTime._convert_to_datetime(datetime_string)
@@ -85,7 +101,18 @@ class FameTime:
 
     @staticmethod
     def _convert_to_datetime(datetime_string: str) -> dt.datetime:
-        """Converts given `datetime_string` to real-world datetime"""
+        """
+        Converts given `datetime_string` in FAME formatting to real-world datetime
+
+        Args:
+            datetime_string: to be converted to datetime
+
+        Returns:
+            datetime representation of provided string
+
+        Raises:
+            ConversionError: if provided string could not be converted, logged with level "ERROR"
+        """
         try:
             return dt.datetime.strptime(datetime_string, DATE_FORMAT)
         except ValueError as e:
@@ -94,8 +121,17 @@ class FameTime:
     @staticmethod
     def convert_fame_time_step_to_datetime(fame_time_steps: int, date_format: str = DATE_FORMAT) -> str:
         """
-        Converts given `fame_time_steps` to corresponding real-world datetime string in `date_format`,
-        raises ConversionException if invalid `date_format` received.
+        Converts given `fame_time_steps` to corresponding real-world datetime string in `date_format`
+
+        Args:
+            fame_time_steps: an integer representing time in FAME's internal format
+            date_format: to be used for datetime representation
+
+        Returns:
+            string representing the real-world datetime of the provided time steps
+
+        Raises:
+            ConversionError: if `date_format` is invalid, logged with level "ERROR"
         """
         years_since_start_time = math.floor(fame_time_steps / Constants.STEPS_PER_YEAR)
         current_year = years_since_start_time + Constants.FIRST_YEAR
@@ -110,21 +146,33 @@ class FameTime:
 
     @staticmethod
     def convert_time_span_to_fame_time_steps(value: int, unit: TimeUnit) -> int:
-        """Converts value of `TimeUnit.UNIT` to fame time steps"""
+        """
+        Converts value of `TimeUnit.UNIT` to FAME time steps
+
+        Args:
+            value: amount of the units to be converted
+            unit: base time unit
+
+        Returns:
+            FAME time steps equivalent of `value x unit`
+
+        Raises:
+            ConversionError: if an unknown time unit is used, logged with level "ERROR"
+        """
         steps = Constants.steps_per_unit.get(unit)
         if steps:
             return steps * value
         raise log_error(ConversionError(FameTime._TIME_UNIT_UNKNOWN.format(unit)))
 
     @staticmethod
-    def is_datetime(string: str) -> bool:
+    def is_datetime(string: Any) -> bool:
         """Returns `True` if given `string` matches Datetime string format and can be converted to FAME time step"""
         if isinstance(string, str):
             return DATE_REGEX.fullmatch(string.strip()) is not None
         return False
 
     @staticmethod
-    def is_fame_time_compatible(value: Union[int, str]) -> bool:
+    def is_fame_time_compatible(value: int | str) -> bool:
         """Returns `True` if given int or string `value` can be converted to a FAME time step"""
         if isinstance(value, int):
             return True
@@ -142,14 +190,23 @@ class FameTime:
         return True
 
     @staticmethod
-    def convert_string_if_is_datetime(value: Union[int, str]) -> int:
+    def convert_string_if_is_datetime(value: int | str) -> int:
         """
-        Returns FAME time steps If given `value` is a valid FAME datetime string it is converted to FAME time steps;
-        Or, if given `value` is an integer, it is returned without modification.
-        Raises an Exception if given `value` is neither a valid FAME datetime string nor an integer value
+        Returns FAME time steps of given `value`. If it is a valid FAME datetime string it is converted to
+        FAME time steps, or, if given `value` is an integer, it is returned without modification.
+
+        Args:
+            value: to be converted
+
+        Returns:
+            FAME time steps equivalent of provided value
+
+        Raises:
+            ConversionError: if given `value` is neither a FAME datetime string nor an integer value,
+                logged with level "ERROR"
         """
         if FameTime.is_datetime(value):
-            return int(FameTime.convert_datetime_to_fame_time_step(value))
+            return int(FameTime.convert_datetime_to_fame_time_step(value))  # type: ignore[arg-type]
         try:
             return int(value)
         except ValueError as e:

fameio/tools.py

@@ -1,8 +1,10 @@
 # SPDX-FileCopyrightText: 2025 German Aerospace Center <fame@dlr.de>
 #
 # SPDX-License-Identifier: Apache-2.0
+from __future__ import annotations
+
 from pathlib import Path
-from typing import Any, Union
+from typing import Any
 
 
 def keys_to_lower(dictionary: dict[str, Any]) -> dict[str, Any]:
@@ -17,12 +19,12 @@ def ensure_is_list(value: Any) -> list:
     return [value]
 
 
-def ensure_path_exists(path: Union[Path, str]):
+def ensure_path_exists(path: Path | str):
     """Creates a specified path if not already existent"""
     Path(path).mkdir(parents=True, exist_ok=True)
 
 
 def clean_up_file_name(name: str) -> str:
-    """Returns given `name` with replacements defined in `replace_map`"""
-    replace_map = {" ": "_", ":": "_", "/": "-"}
-    return name.translate(str.maketrans(replace_map))
+    """Returns given `name` replacing spaces and colons with underscore, and slashed with a dash"""
+    translation_table = str.maketrans({" ": "_", ":": "_", "/": "-"})
+    return name.translate(translation_table)

{fameio-3.1.1.dist-info → fameio-3.2.0.dist-info}/METADATA

@@ -1,8 +1,7 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.3
 Name: fameio
-Version: 3.1.1
+Version: 3.2.0
 Summary: Tools for input preparation and output digestion of FAME models
-Home-page: https://gitlab.com/fame-framework/wiki/-/wikis/home
 License: Apache-2.0
 Keywords: FAME,fameio,agent-based modelling,energy systems
 Author: Felix Nitsch
@@ -20,24 +19,28 @@ Classifier: Programming Language :: Python :: 3.9
 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: Topic :: Scientific/Engineering
-Requires-Dist: fameprotobuf (>=2.0.2,<3.0.0)
+Requires-Dist: fameprotobuf (>=2.0.2,<3.0)
 Requires-Dist: pandas (>=1.0,<3.0)
 Requires-Dist: pyyaml (>=6.0,<7.0)
-Project-URL: Repository, https://gitlab.com/fame-framework/fame-io/
+Project-URL: Changelog, https://gitlab.com/fame-framework/fame-io/-/blob/main/CHANGELOG.md
+Project-URL: Homepage, https://helmholtz.software/software/fame
+Project-URL: Issue Tracking, https://gitlab.com/fame-framework/fame-io/-/issues
+Project-URL: Repository, https://gitlab.com/fame-framework/fame-io
 Description-Content-Type: text/markdown
 
 <!-- SPDX-FileCopyrightText: 2025 German Aerospace Center <fame@dlr.de>
 
 SPDX-License-Identifier: Apache-2.0 -->
 
-|               |                                                                                                                                                                                                                                                                                                                                             |
-|---------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| **Package**   | [![PyPI version](https://badge.fury.io/py/fameio.svg)](https://badge.fury.io/py/fameio) [![PyPI license](https://img.shields.io/pypi/l/fameio.svg)](https://badge.fury.io/py/fameio) [![REUSE status](https://api.reuse.software/badge/gitlab.com/fame-framework/fame-io)](https://api.reuse.software/info/gitlab.com/fame-framework/fame-io) |
-| **Tests**     | [![pipeline status](https://gitlab.com/fame-framework/fame-io/badges/main/pipeline.svg)](https://gitlab.com/fame-framework/fame-io/commits/main) [![coverage report](https://gitlab.com/fame-framework/fame-io/badges/main/coverage.svg)](https://gitlab.com/fame-framework/fame-io/-/commits/main)                                         |
-| **Activity**  | ![GitLab last commit](https://img.shields.io/gitlab/last-commit/fame-framework%2Ffame-io) ![GitLab closed issues by-label](https://img.shields.io/gitlab/issues/closed/fame-framework%2Ffame-io)                                                                                                                                            |
-| **Style**     | [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black) [![Common Changelog](https://common-changelog.org/badge.svg)](https://common-changelog.org) [![linting: pylint](https://img.shields.io/badge/linting-pylint-green)](https://github.com/pylint-dev/pylint)                                                                                                                               |
-| **Reference** | [![JOSS](https://joss.theoj.org/papers/10.21105/joss.04958/status.svg)](https://doi.org/10.21105/joss.04958) [![Zenodo](https://zenodo.org/badge/DOI/10.5281/zenodo.4314337.svg)](https://doi.org/10.5281/zenodo.4314337)                                                                                                                   |
+|               |                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+|---------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| **Package**   | ![PyPI - Python Version](https://img.shields.io/pypi/pyversions/fameio) ![PyPI - Version](https://img.shields.io/pypi/v/fameio) [![PyPI license](https://img.shields.io/pypi/l/fameio.svg)](https://badge.fury.io/py/fameio) [![REUSE status](https://api.reuse.software/badge/gitlab.com/fame-framework/fame-io)](https://api.reuse.software/info/gitlab.com/fame-framework/fame-io)                                                  |
+| **Test**      | [![pipeline status](https://gitlab.com/fame-framework/fame-io/badges/main/pipeline.svg)](https://gitlab.com/fame-framework/fame-io/commits/main) [![coverage report](https://gitlab.com/fame-framework/fame-io/badges/main/coverage.svg)](https://gitlab.com/fame-framework/fame-io/-/commits/main)                                                                                                                                    |
+| **Activity**  | ![GitLab last commit](https://img.shields.io/gitlab/last-commit/fame-framework%2Ffame-io) ![GitLab closed issues by-label](https://img.shields.io/gitlab/issues/closed/fame-framework%2Ffame-io)                                                                                                                                                                                                                                       |
+| **Style**     | [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black) [![log style - common changelog](https://img.shields.io/badge/log_style-common_changelog-blue)](https://common-changelog.org/) ![Static Badge](https://img.shields.io/badge/type%20checked-mypy-039dfc) [![linting: pylint](https://img.shields.io/badge/linting-pylint-green)](https://github.com/pylint-dev/pylint) |
+| **Reference** | [![JOSS](https://joss.theoj.org/papers/10.21105/joss.04958/status.svg)](https://doi.org/10.21105/joss.04958) [![Zenodo](https://zenodo.org/badge/DOI/10.5281/zenodo.4314337.svg)](https://doi.org/10.5281/zenodo.4314337)                                                                                                                                                                                                              |
 
 # FAME-Io
 
@@ -362,7 +365,9 @@ Agent Parameters:
 * `Attributes` Optional; if the agent has any attributes, specify them here in the format "AttributeName: value"; please
   see attribute table above
 * `Metadata` Optional; can be assigned to each instance of an Agent, as well as to each of its Attributes
+* `Ext` Optional; Reserved key for parameters not used by fameio but its extensions, e.g., FAME-Gui
 
+A warning is logged for any other key at this level.
 The specified `Attributes` for each agent must match the specified `Attributes` options in the linked Schema (see
 above).
 For better structure and readability of the `scenario.yaml`, `Attributes` may also be specified in a nested way as
@@ -642,7 +647,7 @@ These CSV files follow a specific structure:
 * They should contain exactly two columns - any other columns are ignored.
   A warning is raised if more than two non-empty columns are detected.
 * The first column must be a time stamp in form `YYYY-MM-DD_hh:mm:ss` or
-  a [FAME-Timestamp](https://gitlab.com/fame-framework/wiki/-/wikis/architecture/decisions/TimeStamp) integer value
+  a [FAME-Timestamp](https://gitlab.com/fame-framework/wiki/-/wikis/architecture/decisions/TimeStamp) integer value.
 * The second column must be a numerical value (either integer or floating-point)
 * The separator of the two columns is a semicolon
 * The data must **not** have headers, except for comments marked with `#`
@@ -662,6 +667,7 @@ Please refer also to the detailed article about `TimeStamps` in
 the [FAME-Wiki](https://gitlab.com/fame-framework/wiki/-/wikis/TimeStamp).
 For large CSV files (with more than 20,000 rows) we recommend using the integer representation of FAME-Timestamps in the
 first column (instead of text representation) to improve conversion speed.
+A warning will be raised for very large files (exceeding 50,000 rows) that require time stamp conversion.
 
 ### Split and join multiple YAML files