ZZX Class#

Summary#

The ZZX class allows for rapid reading of Flood Modeller’s native results format (.zzx). The class must be intiated with the full filepath to a given zzx file:

from floodmodeller_api import ZZX

results = ZZX('path/to/results.zzx')

Reference#

class floodmodeller_api.ZZX(zzn_filepath: str | Path | None = None, from_json: bool = False)#

Reads and processes Flood Modeller 1D binary results format ‘.zzx’

Parameters:: zzx_filepath (str) – Full filepath to model zzx file

Output:: Initiates ‘ZZX’ class object

to_dataframe(*args, **kwargs) → Series | DataFrame#

Loads ZZX 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’} | ‘Left FP h’ | ‘Link inflow’ | ‘Right FP h’ | ‘Right FP mode’ | ‘Left FP mode’ Specify a single output variable (e.g ‘link inflow’). 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()

export_to_csv(*args, **kwargs) → None#

Exports ZZX 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’} | ‘Left FP h’ | ‘Link inflow’ | ‘Right FP h’ | ‘Right FP mode’ | ‘Left FP mode’ Specify a single output variable (e.g ‘link inflow’). 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(*args, **kwargs) → str#

Loads ZZX 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’} | ‘Left FP h’ | ‘Link inflow’ | ‘Right FP h’ | ‘Right FP mode’ | ‘Left FP mode’ Specify a single output variable (e.g ‘link inflow’). 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 results.

Return type:

str

Examples#

Example 1 - Reading and exporting 1D results

The following example shows a simple case of using the ZZX class to read a .zzx file and return the maximum results as a dataframe.

from floodmodeller_api import ZZX

zzx = ZZX("..\\Data\\Examples\\1D\\Flow\\EVENT DATA EXAMPLE.zzx")

zzx.to_dataframe(result_type='max')

This would return the following pandas dataframe object:

         Max Link inflow  Max Left FP h  Max Right FP h  Max Left FP mode  Max Right FP mode
Label
resin                0.0   -9999.990234    -9999.990234               1.0                1.0
CS26                 0.0   -9999.990234    -9999.990234               1.0                1.0
CS25                 0.0   -9999.990234    -9999.990234               1.0                1.0
RD25Sd               0.0   -9999.990234    -9999.990234               1.0                1.0
CS24                 0.0   -9999.990234    -9999.990234               1.0                1.0
FOOTBRu              0.0   -9999.990234    -9999.990234               1.0                1.0
FOOTBRd              0.0   -9999.990234    -9999.990234               1.0                1.0
FOOTb                0.0   -9999.990234    -9999.990234               1.0                1.0
DS3                  0.0   -9999.990234    -9999.990234               1.0                1.0
DS4                  0.0   -9999.990234    -9999.990234               1.0                1.0

Additional options can be specified in the to_dataframe() method to access subsets of results:

zzx.to_dataframe(result_type='max', variable='Flow', include_time=True)

          Max Link inflow  Max Link inflow Time(hrs)
 Label
 resin                0.0                        0.0
 CS26                 0.0                        0.0
 CS25                 0.0                        0.0
 RD25Sd               0.0                        0.0
 CS24                 0.0                        0.0
 FOOTBRu              0.0                        0.0
 FOOTBRd              0.0                        0.0
 FOOTb                0.0                        0.0
 DS3                  0.0                        0.0
 DS4                  0.0                        0.0

The ZZX class can also be used to directly access the metadata stored within the zzx file, using the meta property - a dictionary containing the following data:

ZZX class ‘meta’ keys

Key	Data Type	Description
`zzx_name`	String	Full path to ZZX 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)