ZZN Class#
Summary#
The ZZN class allows for rapid reading of Flood Modeller’s native results format (.zzn). The class must be intiated with the full filepath to a given zzn file:
from floodmodeller_api import ZZN
results = ZZN('path/to/results.zzn')
Reference#
- class floodmodeller_api.ZZN(zzn_filepath: str | Path | None = None, from_json: bool = False)#
Reads and processes Flood Modeller 1D binary results format ‘.zzn’
- Parameters:
zzn_filepath (str) – Full filepath to model zzn file
- Output:
Initiates ‘ZZN’ class object
- to_dataframe(result_type: str = 'all', variable: str = 'all', include_time: bool = False, multilevel_header: bool = True) Series | DataFrame#
Loads zzn results to pandas dataframe object.
- Parameters:
result_type (str, optional) – {‘all’} | ‘max’ | ‘min’ Define whether to return all timesteps or just max/min results. Defaults to ‘all’.
variable (str, optional) – {‘all’} | ‘Flow’ | ‘Stage’ | ‘Froude’ | ‘Velocity’ | ‘Mode’ | ‘State’ Specify a single output variable (e.g ‘flow’ or ‘stage’). Defaults to ‘all’.
include_time (bool, optional) – Whether to include the time of max or min results. Defaults to False.
multilevel_header (bool, optional) – If True, the returned dataframe will have multi-level column headers with the variable as first level and node label as second header. If False, the column names will be formatted “{node label}_{variable}”. Defaults to True.
- Returns:
dataframe object of simulation results
- Return type:
pandas.DataFrame()
- to_dict_of_dataframes(variable: str = 'all') dict#
Loads zzn results to a dictionary of pandas dataframe objects.
- Parameters:
variable (str, optional) – {‘all’} | ‘Flow’ | ‘Stage’ | ‘Froude’ | ‘Velocity’ | ‘Mode’ | ‘State’ Specify a single output variable (e.g ‘flow’ or ‘stage’) or any combination passed as comma separated variable names. Defaults to ‘all’.
- Returns:
dictionary of dataframe object of simulation results, keys corresponding to variables.
- Return type:
dict
- export_to_csv(save_location: str | Path = 'default', result_type: str = 'all', variable: str = 'all', include_time: bool = False) None#
Exports zzn results to CSV file.
- Parameters:
save_location (str, optional) – {default} | folder or file path Full or relative path to folder or csv file to save output csv, if no argument given or if set to ‘default’ then CSV will be saved in same location as ZZN file. Defaults to ‘default’.
result_type (str, optional) – {all} | max | min Define whether to output all timesteps or just max/min results. Defaults to ‘all’.
variable (str, optional) – {‘all’} | ‘Flow’ | ‘Stage’ | ‘Froude’ | ‘Velocity’ | ‘Mode’ | ‘State’ Specify a single output variable (e.g ‘flow’ or ‘stage’). Defaults to ‘all’.
include_time (bool, optional) – Whether to include the time of max or min results. Defaults to False.
- Raises:
Exception – Raised if result_type set to invalid option
- to_json(result_type: str = 'all', variable: str = 'all', include_time: bool = False, multilevel_header: bool = True) str#
Loads zzn results to JSON object.
- Parameters:
result_type (str, optional) – {‘all’} | ‘max’ | ‘min’ Define whether to return all timesteps or just max/min results. Defaults to ‘all’.
variable (str, optional) – {‘all’} | ‘Flow’ | ‘Stage’ | ‘Froude’ | ‘Velocity’ | ‘Mode’ | ‘State’ Specify a single output variable (e.g ‘flow’ or ‘stage’). Defaults to ‘all’.
include_time (bool, optional) – Whether to include the time of max or min results. Defaults to False.
multilevel_header (bool, optional) – If True, the returned dataframe will have multi-level column headers with the variable as first level and node label as second header. If False, the column names will be formatted “{node label}_{variable}”. Defaults to True.
- Returns:
A JSON string representing the ZZN results.
- Return type:
str
Examples#
Example 1 - Reading and exporting 1D results
The following example shows a simple case of using the ZZN class to read a .zzn file and return the maximum results as a dataframe.
from floodmodeller_api import ZZN
zzn = ZZN("..\\Data\\Examples\\1D\\Flow\\EVENT DATA EXAMPLE.zzn")
zzn.to_dataframe(result_type='max')
This would return the following pandas dataframe object:
Max Flow Max Stage Max Froude Max Velocity Max Mode Max State
Node Label
S1 57.537834 6.530089 0.238329 1.348901 16.849001 0.0
CC10 57.533329 6.501225 0.241019 1.361004 16.761000 0.0
S3 57.529274 6.471688 0.243707 1.373160 16.671000 0.0
S4 57.525696 6.441376 0.246524 1.385859 16.580000 0.0
S5 57.522621 6.410248 0.249483 1.399160 16.487000 0.0
S6 57.520054 6.378240 0.252599 1.413122 16.393000 0.0
S7 57.518013 6.345287 0.255887 1.427803 16.298000 0.0
S8 57.516495 6.311316 0.259364 1.443274 16.200001 0.0
S9 57.515556 6.276238 0.263051 1.459620 16.101000 0.0
S10 57.515236 6.240000 0.266915 1.476720 16.000000 0.0
Additional options can be specified in the to_dataframe() method to access subsets of results:
zzn.to_dataframe(result_type='max', variable='Flow', include_time=True)
Max Flow Max Flow Time(hrs)
Node Label ...
S1 57.537834 6.0
CC10 57.533329 6.0
S3 57.529274 6.0
S4 57.525696 6.0
S5 57.522621 6.0
S6 57.520054 6.0
S7 57.518013 6.0
S8 57.516495 6.0
S9 57.515556 6.0
S10 57.515236 6.0
The ZZN class can also be used to directly access the metadata stored within the zzn file, using the meta property - a dictionary containing the following data:
ZZN class ‘meta’ keys
Key |
Data Type |
Description |
|---|---|---|
|
String |
Full path to ZZN file |
|
List of strings |
Array of node labels |
|
String |
Model title including DAT file and Flood Modeller version |
|
Float |
Model timestep (s) |
|
Integer |
Number of model nodes |
|
Float |
Simulation save interval (s) |