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

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
`zzn_name`	String	Full path to ZZN file
`labels`	List of strings	Array of node labels
`model_title`	String	Model title including DAT file and Flood Modeller version
`dt`	Float	Model timestep (s)
`nnodes`	Integer	Number of model nodes
`save_int`	Float	Simulation save interval (s)