Res1D
Res1D(
self,
file_path=None,
reaches=None,
nodes=None,
catchments=None,
time=None,
step_every=None,
quantities=None,
derived_quantities=None,
**kwargs,
)Class for reading data from 1D network result files.
Currently supported formats are:
- MIKE 1D network and catchment res1d files
- MIKE 1D Long Term Statistics (LTS) res1d files
- EPANET res, resx, and whr files generated by MIKE+
- SWMM out files
- MOUSE legacy prf, crf, and xrf files
- MIKE 11 res11 files
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| file_path | str | Path | File path of the result file. | None |
| reaches | list[str] | None | Reach IDs to include when pre-loading dynamic results. None includes all. | None |
| nodes | list[str] | None | Node IDs to include when pre-loading dynamic results. None includes all. | None |
| catchments | list[str] | None | Catchment IDs to include when pre-loading dynamic results. None includes all. | None |
| time | Union[tuple[str], list[str], slice, None] | Start and end time of the data to read. Using None will read all data. | None |
| step_every | int | None | Number specifying the time step frequency to output. None outputs all time steps. | None |
| quantities | list[str] | None | Quantities to filter by (e.g. ‘WaterLevel’, ‘Discharge’). None includes all. | None |
| derived_quantities | list[str] | None | Derived quantities to include when pre-loading dynamic results. None includes all. | None |
Examples
Read all data from a res1d file into a Pandas DataFrame:
>>> res = Res1D("results.res1d")
>>> res.read()Read all available data for nodes:
>>> res1d.nodes.read()Read data for a specific node:
>>> res.nodes['node1'].read()Read data for a specific quantity:
>>> res.nodes['node1'].WaterLevel.read()Filter which data is pre-loaded, typically used for large files:
>>> nodes = ['node1', 'node2']
>>> reaches = ['reach1', 'reach2']
>>> times = slice('2020-01-01', '2020-01-02')
>>> res1d = Res1D('MyRes1D.res1d', nodes=nodes, reaches=reaches, time=times)
>>> res1d.read()Only read every second time step:
>>> res1d = Res1D('MyRes1D.res1d', step_every=2)
>>> res1d.read()Attributes
| Name | Description |
|---|---|
| catchments | Catchments of the result file. See ResultCatchments. |
| data | .NET object ResultData with the loaded res1d data. |
| derived_quantities | Derived quantities available for res1d file. |
| end_time | End time of the result file. |
| file_path | File path of the result file. |
| global_data | Global data of the result file. See ResultGlobalDatas. |
| nodes | Nodes of the result file. See ResultNodes. |
| number_of_time_steps | Number of time steps in the result file. |
| projection_string | Projection string of the result file. |
| quantities | Quantities in res1d file. |
| query | .NET object ResultDataQuery to use for querying the loaded res1d data. |
| reaches | Reaches of the result file. See ResultReaches. |
| result_data | .NET object ResultData with the loaded res1d data. |
| result_type | Specifies what type of result file Res1D is. |
| searcher | .NET object ResultDataSearcher to use for searching res1d data items on network. |
| start_time | Start time of the result file. |
| structures | Structures of the result file. See ResultStructures. |
| time_index | pandas.DatetimeIndex of the time index. |
Methods
| Name | Description |
|---|---|
| add_derived_quantity | Add a derived quantity to the Res1D object, propogating changes to the network. |
| extract | Extract given queries to provided file. |
| get_supported_file_extensions | Get supported file extensions for Res1D. |
| info | Print information about the result file. |
| merge | Merge res1d files. |
| modify | Modify the result data. |
| read | Read result data into a pandas DataFrame. |
| remove_derived_quantity | Remove a derived quantity from the Res1D object, propogating changes to the network. |
| save | Save the ResultData to a new res1d file. |
| to_csv | Extract to csv file. |
| to_dfs0 | Extract to dfs0 file. |
| to_txt | Extract to txt file. |
add_derived_quantity
Res1D.add_derived_quantity(derived_quantity)Add a derived quantity to the Res1D object, propogating changes to the network.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| derived_quantity | Type[DerivedQuantity] | Derived quantity to be added | required |
extract
Res1D.extract(file_path, queries=None, time_step_skipping_number=1, ext=None)Extract given queries to provided file.
File type is determined from file_path extension. The supported formats are:
- csv
- dfs0
- txt
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| file_path | str | Output file path. | required |
| queries | Optional[List[QueryData] | QueryData | List[TimeSeriesId] | TimeSeriesId] | A list of queries to read. If None, all data is read. | None |
| time_step_skipping_number | int | Number specifying the time step frequency to output. | 1 |
| ext | str | Output file type to use instead of determining it from extension. Can be ‘csv’, ‘dfs0’, ‘txt’. | None |
Notes
The queries parameter exists for historical reasons where queries were built manually. Now, this is handled automatically e.g. res.nodes['node1'].WaterLevel.read(). It may still be useful so it has been kept for now.
get_supported_file_extensions
Res1D.get_supported_file_extensions()Get supported file extensions for Res1D.
info
Res1D.info()Print information about the result file.
merge
Res1D.merge(file_names, merged_file_name)Merge res1d files.
It is possible to merge three kinds of result files:
- Regular res1d (HD, RR, etc.)
- LTS extreme statistics
- LTS chronological statistics
For regular res1d files the requirement is that the simulation start time of the first file matches the simulation end time of the second file (the same principle for subsequent files).
For LTS result files, meaningful merged result file is obtained when simulation periods for the files do not overlap.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| file_names | list of str or Res1D objects | List of res1d file names to merge. | required |
| merged_file_name | str | File name of the res1d file to store the merged data. | required |
modify
Res1D.modify(data_frame, file_path=None)Modify the result data.
Note that this only modifies the data in memory, not the original file. To save the modified data to a new file, use save. Alternatively, use file_path to save the modified data to a new file.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| data_frame | pandas.DataFrame | pandas.DataFrame with the new data, with columns matching data generated by read. |
required |
| file_path | str | File path for the new res1d file. Optional. | None |
Notes
This modifies the .NET ResutlData’s TimeData object.
Examples
>>> res = Res1D('results.res1d')
>>> data = res.read()
>>> data += 100
>>> res.modify(data)read
Res1D.read(queries=None, column_mode=None)Read result data into a pandas DataFrame.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| queries | Optional[list[TimeSeriesId] | TimeSeriesId | list[QueryData] | QueryData] | A list of queries to read. If None, all data is read. | None |
| column_mode | ('str', 'timeseries', 'compact', 'all') | Specifies the type of column index of returned DataFrame. | 'str' |
Returns
| Name | Type | Description |
|---|---|---|
| pd.DataFrame |
Notes
The queries parameter exists for historical reasons where queries were built manually. Now, this is handled automatically e.g. res.nodes['node1'].WaterLevel.read(). It may still be useful so it has been kept for now.
Examples
>>> res = Res1D('results.res1d')
>>> res.read()remove_derived_quantity
Res1D.remove_derived_quantity(derived_quantity)Remove a derived quantity from the Res1D object, propogating changes to the network.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| derived_quantity | DerivedQuantity | str | Derived quantity to be removed. Either DerivedQuantity class or its name. | required |
save
Res1D.save(file_path)Save the ResultData to a new res1d file.
Useful for persisting modified data, as well as converting supported result file types (e.g. res11) into res1d.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| file_path | str | File path for the new res1d file. | required |
Examples
>>> res11_data = Res1D('results.res11')
>>> res11_data.save('results.res1d')to_csv
Res1D.to_csv(file_path, queries=None, time_step_skipping_number=1)Extract to csv file.
Same as extract but with ext set to ‘csv’.
to_dfs0
Res1D.to_dfs0(file_path, queries=None, time_step_skipping_number=1)Extract to dfs0 file.
Same as extract but with ext set to ‘dfs0’.
to_txt
Res1D.to_txt(file_path, queries=None, time_step_skipping_number=1)Extract to txt file.
Same as extract but with ext set to ‘txt’.