fameio 3.2.0__tar.gz → 3.4.0__tar.gz

{fameio-3.2.0 → fameio-3.4.0}/CHANGELOG.md

@@ -2,6 +2,27 @@
 
 SPDX-License-Identifier: CC0-1.0 -->
 
+##  [3.4.0](https://gitlab.com/fame-framework/fame-io/-/tags/v3.4.0) - 2025-05-27
+### Changed
+- Allow nesting of sender or receiver lists in contracts !228 (@dlr-cjs)
+
+### Added
+- Add new keyword "Every" to Contracts that allow text qualification of Contract duration #249 (@dlr-cjs)
+- Add helper method to return first time stamp of a given year #247 (@dlr-cjs)
+- Add checks for Python 3.13 to CI #250 (@dlr-cjs)
+
+### Fixed
+- Avoid causing a traceback by nested contract sender or receiver lists #228 (@dlr-cjs)
+
+## [3.3.0](https://gitlab.com/fame-framework/fame-io/-/tags/v3.3.0) - 2025-05-09
+### Changed
+- Expose static methods to read, convert, and write time series #245 (@dlr-cjs)
+- Improve docstrings of SchemaValidator !219 (@dlr-cjs)
+
+### Added
+- Add command-line script to reformat time series #246 (@dlr-cjs)
+- Read execution metadata from protobuf file #193 (@dlr-cjs)
+
 ## [3.2.0](https://gitlab.com/fame-framework/fame-io/-/tags/v3.2.0) - 2025-04-22
 ### Changed
 - Suppress detailed Exception traceback in console #239 (@dlr_fn, @dlr-cjs)

{fameio-3.2.0 → fameio-3.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: fameio
-Version: 3.2.0
+Version: 3.4.0
 Summary: Tools for input preparation and output digestion of FAME models
 License: Apache-2.0
 Keywords: FAME,fameio,agent-based modelling,energy systems
@@ -47,8 +47,7 @@ SPDX-License-Identifier: Apache-2.0 -->
 *Tools for input preparation and output digestion of FAME models*
 
 FAME-Io compiles input for FAME models in protobuf format and extracts model outputs to human-readable files.
-Please visit the [FAME-Wiki](https://gitlab.com/fame-framework/wiki/-/wikis/home) to get an explanation of FAME and its
-components.
+Please visit the [FAME-Wiki](https://gitlab.com/fame-framework/wiki/-/wikis/home) to get an explanation of FAME and its components.
 
 # Installation
 
@@ -56,30 +55,26 @@ We recommend installing `fameio` using PyPI:
 
     pip install fameio
 
-You may also use `pipx`. For detailed information please refer to the
-official `pipx` [documentation](https://github.com/pypa/pipx).
+You may also use `pipx`. For detailed information please refer to the official `pipx` [documentation](https://github.com/pypa/pipx).
 
     pipx install fameio
 
-`fameio` is currently developed and tested for Python 3.8 or higher.
+`fameio` is currently developed and tested for Python 3.9 or higher.
 See the `pyproject.toml` for a complete listing of dependencies.
 
 # Usage
 
-FAME-Io currently offers two main scripts `makeFameRunConfig` and `convertFameResults`.
-Both are automatically installed with the package.
+FAME-Io currently offers two main scripts `makeFameRunConfig` and `convertFameResults`, plus a helper script `reformatTimeSeries`
+All are automatically installed with the package.
 The first one creates a protobuf file for FAME applications using YAML definition files and CSV files.
-The latter one reads output files from FAME applications in protobuf format and converts them to CSV files.
+The second one reads output files from FAME applications in protobuf format and converts them to CSV files.
+The third script reformats time series CSV files to FAME format.
 
-You may use the [example data](https://gitlab.com/dlr-ve/esy/amiris/examples) provided for
-the [AMIRIS](https://gitlab.com/dlr-ve/esy/amiris/amiris) model which can be used to simulate electricity markets
-in [Germany](https://gitlab.com/dlr-ve/esy/amiris/examples/-/tree/main/Germany2019), [Austria](https://gitlab.com/dlr-ve/esy/amiris/examples/-/tree/main/Austria2019),
-and a simple [proof-of-concept model](https://gitlab.com/dlr-ve/esy/amiris/examples/-/tree/main/Simple).
+You may use the [example data](https://gitlab.com/dlr-ve/esy/amiris/examples) provided for the [AMIRIS](https://gitlab.com/dlr-ve/esy/amiris/amiris) model which can be used to simulate electricity markets in [Germany](https://gitlab.com/dlr-ve/esy/amiris/examples/-/tree/main/Germany2019), [Austria](https://gitlab.com/dlr-ve/esy/amiris/examples/-/tree/main/Austria2019), and a simple [proof-of-concept model](https://gitlab.com/dlr-ve/esy/amiris/examples/-/tree/main/Simple).
 
 ## Make a FAME run configuration
 
-Digests configuration files in YAML format, combines them with CSV data files and creates a single input file for FAME
-applications in protobuf format.
+Digests configuration files in YAML format, combines them with CSV data files and creates a single input file for FAME applications in protobuf format.
 Call structure:
 
     makeFameRunConfig -f <path/to/scenario.yaml>
@@ -512,7 +507,7 @@ Contracts:
     ReceiverId: 2
     ProductName: ProductOfAgent_1
     FirstDeliveryTime: -25
-    DeliveryIntervalInSteps: 3600
+    Every: 3600
     Metadata:
       Some: "additional information can go here"
 
@@ -520,7 +515,7 @@ Contracts:
     ReceiverId: 1
     ProductName: ProductOfAgent_2
     FirstDeliveryTime: -22
-    DeliveryIntervalInSteps: 3600
+    Every: 1 hour
     Attributes:
       ProductAppendix: value
       TimeOffset: 42
@@ -532,7 +527,8 @@ Contract Parameters:
 * `ReceiverId` unique ID of agent receiving the product
 * `ProductName` name of the product to be sent
 * `FirstDeliveryTime` first time of delivery in the format "seconds after the January 1st 2000, 00:00:00"
-* `DeliveryIntervalInSteps` delay time in between deliveries in seconds
+* `Every` delay time in between deliveries; either an integer value in seconds, or a qualified time span in the format "<integer> <TimeUnit>(s)", where TimeUnit is one of "second", "minute", "hour", "day", "week", "month", "year" - with an options "s" at the end; mind that week, month, and year refer to fixed-length intervals of 168, 730, and 8760 hours.
+* `DeliveryIntervalInSteps` deprecated; delay time in between deliveries in seconds (use instead of `Every`)
 * `Metadata` can be assigned to add further helpful information about a Contract
 * `Attributes` can be set to include additional information as `int`, `float`, `enum`, or `dict` data types
 
@@ -546,59 +542,72 @@ example:
 ```yaml
 Contracts:
   # effectively 3 similar contracts (0 -> 11), (0 -> 12), (0 -> 13)
-  # with otherwise identical ProductName, FirstDeliveryTime & DeliveryIntervalInSteps
+  # with otherwise identical ProductName, FirstDeliveryTime, and Every
   - SenderId: 0
     ReceiverId: [ 11, 12, 13 ]
     ProductName: MyOtherProduct
     FirstDeliveryTime: 100
-    DeliveryIntervalInSteps: 3600
+    Every: 1 hour
 
   # effectively 3 similar contracts (1 -> 10), (2 -> 10), (3 -> 10)
-  # with otherwise identical ProductName, FirstDeliveryTime & DeliveryIntervalInSteps
+  # with otherwise identical ProductName, FirstDeliveryTime, and Every
   - SenderId: [ 1, 2, 3 ]
     ReceiverId: 10
     ProductName: MyProduct
     FirstDeliveryTime: 100
-    DeliveryIntervalInSteps: 3600
+    Every: 1 hour
 
   # effectively 3 similar contracts (1 -> 11), (2 -> 12), (3 -> 13)
-  # with otherwise identical ProductName, FirstDeliveryTime & DeliveryIntervalInSteps
+  # with otherwise identical ProductName, FirstDeliveryTime, and Every
   - SenderId: [ 1, 2, 3 ]
     ReceiverId: [ 11, 12, 13 ]
     ProductName: MyThirdProduct
     FirstDeliveryTime: 100
-    DeliveryIntervalInSteps: 3600
+    Every: 1 hour
 ```
 
-Combined with YAML anchors complex contract chains can be easily reduced to a minimum of required configuration.
-The following example is equivalent to the previous one and allows a quick extension of contracts to a new couple of
-agents e.g. (4;14):
+When combined with YAML anchors, the complexity of extensive contract chains can be reduced.
+The following example is equivalent to the previous one, enabling contracts to be quickly extended to a new group of agents:
 
 ```yaml
 Groups:
-  - &agentList1: [ 1,2,3 ]
-  - &agentList2: [ 11,12,13 ]
+  - &agentList1: [ 1, 2, 3 ]
+  - &agentList2: [ 11, 12, 13 ]
 
 Contracts:
   - SenderId: 0
     ReceiverId: *agentList2
     ProductName: MyOtherProduct
     FirstDeliveryTime: 100
-    DeliveryIntervalInSteps: 3600
+    Every: 1 hour
 
   - SenderId: *agentList1
     ReceiverId: 10
     ProductName: MyProduct
     FirstDeliveryTime: 100
-    DeliveryIntervalInSteps: 3600
+    Every: 1 hour
 
   - SenderId: *agentList1
     ReceiverId: *agentList2
     ProductName: MyThirdProduct
     FirstDeliveryTime: 100
-    DeliveryIntervalInSteps: 3600
+    Every: 1 hour
 ```
 
+Lists can be nested in senders and receivers as follows:
+
+```
+Groups:
+  - SenderId: 42
+    ReceiverId: [1, [2, 3], [4, [5]]]
+    ProductName: AnImportantProduct
+    FirstDeliveryTime: 101
+    Every: 30 minutes
+```
+
+This feature should not be overused, as nested lists can become messy and difficult to read.
+Special care should be taken when using it with an N-to-N mapping, as it will be difficult to check whether senders and receivers are matched correctly.
+
 #### StringSets
 
 This optional section defines values of type `string_set`.
@@ -644,10 +653,8 @@ TIME_SERIES inputs are not directly fed into the Scenario YAML file.
 Instead, TIME_SERIES reference a CSV file that can be stored some place else.
 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.
+* 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.
 * 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 `#`
@@ -663,11 +670,10 @@ Exemplary content of a valid CSV file:
     2016-01-01_00:00:00;42  # optional comment on this particular data point
     2017-01-01_00:00:00;0.1
 
-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.
+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.
+Use `reformatTimeSeries` to convert one or multiple timeseries CSV files into FAME format to improve conversion speed and avoid this warning.
 
 ### Split and join multiple YAML files
 
@@ -936,6 +942,24 @@ run_config = handle_args(my_arg_string, my_defaults)
 convert_results(run_config)
 ```
 
+## Reformat time series
+
+Takes CSV time series files and reformats them into FAME time format.
+This improves speed of run configuration creation but also reduces readability of the CSV files' content.
+Thus, we recommend to apply this reformatting only for CSV time series files with more than 20,000 lines.
+
+Call structure:
+
+    reformatTimeSeries -fp <file_or_file_pattern*.csv>
+
+You may also specify any of the following arguments:
+
+| Command                       | Action                                                                                                                                                                                 |
+|-------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `-l` or `--log` <option>      | Sets the logging level. Default is `WARNING`. Options are `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`.                                                                             |
+| `-lf` or `--logfile` <file>   | Sets the logging file. Default is `None`. If `None` is provided, all logs get only printed to the console.                                                                             |
+| `--replace` or `--no-replace` | If `--replace` is specified, existing csv files are replaced with the new content. Otherwise and by default, new files are created extending the original file name by "_reformatted". |
+
 ## Cite FAME-Io
 
 If you use FAME-Io for academic work, please cite as follows.

{fameio-3.2.0 → fameio-3.4.0}/README.md

@@ -15,8 +15,7 @@ SPDX-License-Identifier: Apache-2.0 -->
 *Tools for input preparation and output digestion of FAME models*
 
 FAME-Io compiles input for FAME models in protobuf format and extracts model outputs to human-readable files.
-Please visit the [FAME-Wiki](https://gitlab.com/fame-framework/wiki/-/wikis/home) to get an explanation of FAME and its
-components.
+Please visit the [FAME-Wiki](https://gitlab.com/fame-framework/wiki/-/wikis/home) to get an explanation of FAME and its components.
 
 # Installation
 
@@ -24,30 +23,26 @@ We recommend installing `fameio` using PyPI:
 
     pip install fameio
 
-You may also use `pipx`. For detailed information please refer to the
-official `pipx` [documentation](https://github.com/pypa/pipx).
+You may also use `pipx`. For detailed information please refer to the official `pipx` [documentation](https://github.com/pypa/pipx).
 
     pipx install fameio
 
-`fameio` is currently developed and tested for Python 3.8 or higher.
+`fameio` is currently developed and tested for Python 3.9 or higher.
 See the `pyproject.toml` for a complete listing of dependencies.
 
 # Usage
 
-FAME-Io currently offers two main scripts `makeFameRunConfig` and `convertFameResults`.
-Both are automatically installed with the package.
+FAME-Io currently offers two main scripts `makeFameRunConfig` and `convertFameResults`, plus a helper script `reformatTimeSeries`
+All are automatically installed with the package.
 The first one creates a protobuf file for FAME applications using YAML definition files and CSV files.
-The latter one reads output files from FAME applications in protobuf format and converts them to CSV files.
+The second one reads output files from FAME applications in protobuf format and converts them to CSV files.
+The third script reformats time series CSV files to FAME format.
 
-You may use the [example data](https://gitlab.com/dlr-ve/esy/amiris/examples) provided for
-the [AMIRIS](https://gitlab.com/dlr-ve/esy/amiris/amiris) model which can be used to simulate electricity markets
-in [Germany](https://gitlab.com/dlr-ve/esy/amiris/examples/-/tree/main/Germany2019), [Austria](https://gitlab.com/dlr-ve/esy/amiris/examples/-/tree/main/Austria2019),
-and a simple [proof-of-concept model](https://gitlab.com/dlr-ve/esy/amiris/examples/-/tree/main/Simple).
+You may use the [example data](https://gitlab.com/dlr-ve/esy/amiris/examples) provided for the [AMIRIS](https://gitlab.com/dlr-ve/esy/amiris/amiris) model which can be used to simulate electricity markets in [Germany](https://gitlab.com/dlr-ve/esy/amiris/examples/-/tree/main/Germany2019), [Austria](https://gitlab.com/dlr-ve/esy/amiris/examples/-/tree/main/Austria2019), and a simple [proof-of-concept model](https://gitlab.com/dlr-ve/esy/amiris/examples/-/tree/main/Simple).
 
 ## Make a FAME run configuration
 
-Digests configuration files in YAML format, combines them with CSV data files and creates a single input file for FAME
-applications in protobuf format.
+Digests configuration files in YAML format, combines them with CSV data files and creates a single input file for FAME applications in protobuf format.
 Call structure:
 
     makeFameRunConfig -f <path/to/scenario.yaml>
@@ -480,7 +475,7 @@ Contracts:
     ReceiverId: 2
     ProductName: ProductOfAgent_1
     FirstDeliveryTime: -25
-    DeliveryIntervalInSteps: 3600
+    Every: 3600
     Metadata:
       Some: "additional information can go here"
 
@@ -488,7 +483,7 @@ Contracts:
     ReceiverId: 1
     ProductName: ProductOfAgent_2
     FirstDeliveryTime: -22
-    DeliveryIntervalInSteps: 3600
+    Every: 1 hour
     Attributes:
       ProductAppendix: value
       TimeOffset: 42
@@ -500,7 +495,8 @@ Contract Parameters:
 * `ReceiverId` unique ID of agent receiving the product
 * `ProductName` name of the product to be sent
 * `FirstDeliveryTime` first time of delivery in the format "seconds after the January 1st 2000, 00:00:00"
-* `DeliveryIntervalInSteps` delay time in between deliveries in seconds
+* `Every` delay time in between deliveries; either an integer value in seconds, or a qualified time span in the format "<integer> <TimeUnit>(s)", where TimeUnit is one of "second", "minute", "hour", "day", "week", "month", "year" - with an options "s" at the end; mind that week, month, and year refer to fixed-length intervals of 168, 730, and 8760 hours.
+* `DeliveryIntervalInSteps` deprecated; delay time in between deliveries in seconds (use instead of `Every`)
 * `Metadata` can be assigned to add further helpful information about a Contract
 * `Attributes` can be set to include additional information as `int`, `float`, `enum`, or `dict` data types
 
@@ -514,59 +510,72 @@ example:
 ```yaml
 Contracts:
   # effectively 3 similar contracts (0 -> 11), (0 -> 12), (0 -> 13)
-  # with otherwise identical ProductName, FirstDeliveryTime & DeliveryIntervalInSteps
+  # with otherwise identical ProductName, FirstDeliveryTime, and Every
   - SenderId: 0
     ReceiverId: [ 11, 12, 13 ]
     ProductName: MyOtherProduct
     FirstDeliveryTime: 100
-    DeliveryIntervalInSteps: 3600
+    Every: 1 hour
 
   # effectively 3 similar contracts (1 -> 10), (2 -> 10), (3 -> 10)
-  # with otherwise identical ProductName, FirstDeliveryTime & DeliveryIntervalInSteps
+  # with otherwise identical ProductName, FirstDeliveryTime, and Every
   - SenderId: [ 1, 2, 3 ]
     ReceiverId: 10
     ProductName: MyProduct
     FirstDeliveryTime: 100
-    DeliveryIntervalInSteps: 3600
+    Every: 1 hour
 
   # effectively 3 similar contracts (1 -> 11), (2 -> 12), (3 -> 13)
-  # with otherwise identical ProductName, FirstDeliveryTime & DeliveryIntervalInSteps
+  # with otherwise identical ProductName, FirstDeliveryTime, and Every
   - SenderId: [ 1, 2, 3 ]
     ReceiverId: [ 11, 12, 13 ]
     ProductName: MyThirdProduct
     FirstDeliveryTime: 100
-    DeliveryIntervalInSteps: 3600
+    Every: 1 hour
 ```
 
-Combined with YAML anchors complex contract chains can be easily reduced to a minimum of required configuration.
-The following example is equivalent to the previous one and allows a quick extension of contracts to a new couple of
-agents e.g. (4;14):
+When combined with YAML anchors, the complexity of extensive contract chains can be reduced.
+The following example is equivalent to the previous one, enabling contracts to be quickly extended to a new group of agents:
 
 ```yaml
 Groups:
-  - &agentList1: [ 1,2,3 ]
-  - &agentList2: [ 11,12,13 ]
+  - &agentList1: [ 1, 2, 3 ]
+  - &agentList2: [ 11, 12, 13 ]
 
 Contracts:
   - SenderId: 0
     ReceiverId: *agentList2
     ProductName: MyOtherProduct
     FirstDeliveryTime: 100
-    DeliveryIntervalInSteps: 3600
+    Every: 1 hour
 
   - SenderId: *agentList1
     ReceiverId: 10
     ProductName: MyProduct
     FirstDeliveryTime: 100
-    DeliveryIntervalInSteps: 3600
+    Every: 1 hour
 
   - SenderId: *agentList1
     ReceiverId: *agentList2
     ProductName: MyThirdProduct
     FirstDeliveryTime: 100
-    DeliveryIntervalInSteps: 3600
+    Every: 1 hour
 ```
 
+Lists can be nested in senders and receivers as follows:
+
+```
+Groups:
+  - SenderId: 42
+    ReceiverId: [1, [2, 3], [4, [5]]]
+    ProductName: AnImportantProduct
+    FirstDeliveryTime: 101
+    Every: 30 minutes
+```
+
+This feature should not be overused, as nested lists can become messy and difficult to read.
+Special care should be taken when using it with an N-to-N mapping, as it will be difficult to check whether senders and receivers are matched correctly.
+
 #### StringSets
 
 This optional section defines values of type `string_set`.
@@ -612,10 +621,8 @@ TIME_SERIES inputs are not directly fed into the Scenario YAML file.
 Instead, TIME_SERIES reference a CSV file that can be stored some place else.
 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.
+* 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.
 * 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 `#`
@@ -631,11 +638,10 @@ Exemplary content of a valid CSV file:
     2016-01-01_00:00:00;42  # optional comment on this particular data point
     2017-01-01_00:00:00;0.1
 
-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.
+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.
+Use `reformatTimeSeries` to convert one or multiple timeseries CSV files into FAME format to improve conversion speed and avoid this warning.
 
 ### Split and join multiple YAML files
 
@@ -904,6 +910,24 @@ run_config = handle_args(my_arg_string, my_defaults)
 convert_results(run_config)
 ```
 
+## Reformat time series
+
+Takes CSV time series files and reformats them into FAME time format.
+This improves speed of run configuration creation but also reduces readability of the CSV files' content.
+Thus, we recommend to apply this reformatting only for CSV time series files with more than 20,000 lines.
+
+Call structure:
+
+    reformatTimeSeries -fp <file_or_file_pattern*.csv>
+
+You may also specify any of the following arguments:
+
+| Command                       | Action                                                                                                                                                                                 |
+|-------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `-l` or `--log` <option>      | Sets the logging level. Default is `WARNING`. Options are `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`.                                                                             |
+| `-lf` or `--logfile` <file>   | Sets the logging file. Default is `None`. If `None` is provided, all logs get only printed to the console.                                                                             |
+| `--replace` or `--no-replace` | If `--replace` is specified, existing csv files are replaced with the new content. Otherwise and by default, new files are created extending the original file name by "_reformatted". |
+
 ## Cite FAME-Io
 
 If you use FAME-Io for academic work, please cite as follows.

{fameio-3.2.0 → fameio-3.4.0}/pyproject.toml

@@ -7,7 +7,7 @@ build-backend = "poetry.core.masonry.api"
 
 [project]
 name = "fameio"
-version = "3.2.0"
+version = "3.4.0"
 description = "Tools for input preparation and output digestion of FAME models"
 license = "Apache-2.0"
 readme = "README.md"
@@ -39,6 +39,7 @@ repository = "https://gitlab.com/fame-framework/fame-io"
 [project.scripts]
 makeFameRunConfig = "fameio.scripts:makeFameRunConfig"
 convertFameResults = "fameio.scripts:convertFameResults"
+reformatTimeSeries = "fameio.scripts:reformatTimeSeries"
 
 [tool.poetry]
 classifiers = [

{fameio-3.2.0 → fameio-3.4.0}/src/fameio/cli/convert_results.py

@@ -26,8 +26,8 @@ CLI_DEFAULTS = {
     Options.FILE: None,
     Options.LOG_LEVEL: "WARN",
     Options.LOG_FILE: None,
-    Options.AGENT_LIST: None,
     Options.OUTPUT: None,
+    Options.AGENT_LIST: None,
     Options.SINGLE_AGENT_EXPORT: False,
     Options.MEMORY_SAVING: False,
     Options.RESOLVE_COMPLEX_FIELD: ResolveOptions.SPLIT,
@@ -41,8 +41,7 @@ _OUTFILE_PATH_HELP = "Provide path to folder to store output .csv files"
 
 
 def handle_args(args: list[str], defaults: dict[Options, Any] | None = None) -> dict[Options, Any]:
-    """
-    Handles command line arguments and returns `run_config` for convert_results script
+    """Handles command line arguments and returns `run_config` for convert_results script.
 
     Args:
         args: list of (command line) arguments, e.g., ['-f', 'my_file']; arg values take precedence over defaults
@@ -57,8 +56,7 @@ def handle_args(args: list[str], defaults: dict[Options, Any] | None = None) ->
 
 
 def _prepare_parser(defaults: dict[Options, Any] | None) -> argparse.ArgumentParser:
-    """
-    Creates a parser with given defaults to handle `make_config` configuration arguments
+    """Creates a parser with given defaults to handle `make_config` configuration arguments.
 
     Returns:
         new parser using given defaults for its arguments; if a default is not specified, hard-coded defaults are used
@@ -82,5 +80,5 @@ def _prepare_parser(defaults: dict[Options, Any] | None) -> argparse.ArgumentPar
 
 
 def _get_default(defaults: dict, option: Options) -> Any:
-    """Returns default for given `option` or its cli default"""
+    """Returns default for given `option` or its cli default."""
     return defaults.get(option, CLI_DEFAULTS[option])

{fameio-3.2.0 → fameio-3.4.0}/src/fameio/cli/make_config.py

@@ -34,8 +34,7 @@ _ENCODING_HELP = (
 
 
 def handle_args(args: list[str], defaults: dict[Options, Any] | None = None) -> dict[Options, Any]:
-    """
-    Converts given `arguments` and returns a configuration for the make_config script
+    """Converts given `args` and returns a configuration for the make_config script.
 
     Args:
         args: list of (command line) arguments, e.g., ['-f', 'my_file']; arg values take precedence over defaults
@@ -50,8 +49,7 @@ def handle_args(args: list[str], defaults: dict[Options, Any] | None = None) ->
 
 
 def _prepare_parser(defaults: dict[Options, Any] | None) -> argparse.ArgumentParser:
-    """
-    Creates a parser with given defaults to handle `make_config` configuration arguments
+    """Creates a parser with given defaults to handle `make_config` configuration arguments.
 
     Returns:
         new parser using given defaults for its arguments; if a default is not specified, hard-coded defaults are used
@@ -67,5 +65,5 @@ def _prepare_parser(defaults: dict[Options, Any] | None) -> argparse.ArgumentPar
 
 
 def _get_default(defaults: dict, option: Options) -> Any:
-    """Returns default for given `option` or, if missing, its cli default"""
+    """Returns default for given `option` or, if missing, its cli default."""
     return defaults.get(option, CLI_DEFAULTS[option])

{fameio-3.2.0 → fameio-3.4.0}/src/fameio/cli/options.py

@@ -6,7 +6,7 @@ from enum import Enum, auto
 
 
 class ParsableEnum(Enum):
-    """Extend this to create an enum that can be parsed with argparse"""
+    """Extend this to create an enum that can be parsed with argparse."""
 
     @classmethod
     def instantiate(cls, name: str) -> Enum:
@@ -20,7 +20,7 @@ class ParsableEnum(Enum):
 
 
 class Options(Enum):
-    """Specifies command line configuration options"""
+    """Specifies command line configuration options."""
 
     FILE = auto()
     LOG_LEVEL = auto()
@@ -34,10 +34,12 @@ class Options(Enum):
     TIME_MERGING = auto()
     INPUT_RECOVERY = auto()
     INPUT_ENCODING = auto()
+    FILE_PATTERN = auto()
+    REPLACE = auto()
 
 
 class TimeOptions(ParsableEnum, Enum):
-    """Specifies options for conversion of time in output"""
+    """Specifies options for conversion of time in output."""
 
     INT = auto()
     UTC = auto()
@@ -45,7 +47,7 @@ class TimeOptions(ParsableEnum, Enum):
 
 
 class ResolveOptions(ParsableEnum, Enum):
-    """Specifies options for resolving complex fields in output files"""
+    """Specifies options for resolving complex fields in output files."""
 
     IGNORE = auto()
     SPLIT = auto()