Tip

1. Need help? Please let us know in the SUEWS Community.

2. Please report issues with the manual on GitHub Issues (or use Report Issue for This Page for page-specific feedback).

3. Please cite SUEWS with proper information from our Zenodo page.

6.3. Utility Functions

SuPy provides a comprehensive set of utility functions for data processing, analysis, and visualisation.

6.3.1. ERA-5 Data Processing

Functions for downloading and processing ERA-5 reanalysis data:

gen_forcing_era5(lat_x, lon_x, start, end[, ...])

Generate SUEWS forcing files using ERA-5 timeseries data.

6.3.2. Meteorological Data

Functions for working with EPW weather files and meteorological data:

gen_epw(df_output, lat, lon[, tz, path_epw, ...])	Generate an epw file of uTMY (urbanised Typical Meteorological Year) using SUEWS simulation results.
read_epw(path_epw[, target_height, z0m])	Read in EPW (EnergyPlus Weather) file as a DataFrame.
fill_gap_all(ser_to_fill[, freq, ...])	Fill all gaps in a time series using data from neighbouring divisions of 'freq'

6.3.3. Energy Balance Analysis

Functions for analysing the Objective Hysteresis Model (OHM):

derive_ohm_coef(ser_QS, ser_QN)	A function to linearly fit two independant variables to a dependent one.
sim_ohm(ser_qn, a1, a2, a3)	Calculate QS using OHM (Objective Hysteresis Model).

6.3.4. Surface Conductance

Functions for calculating and calibrating surface conductance:

cal_gs_suews(kd, ta_c, rh, pa, smd, lai, ...)	Model surface conductance/resistance using phenology and atmospheric forcing conditions.
cal_gs_obs(qh, qe, ta, rh, pa, ra)	Calculate surface conductance based on observations, notably turbulent fluxes.
calib_g(df_fc_suews, ser_ra, g_max, lai_max, ...)	Calibrate parameters for modelling surface conductance over vegetated surfaces using LMFIT.

6.3.5. Plotting and Visualisation

Functions for visualising SUEWS results:

plot_comp(df_var[, scatter_kws, kde_kws, ...])	Produce a scatter plot with linear regression line to compare simulation results and observations.
plot_day_clm(df_var[, fig, ax, show_dif, ...])	Produce a ensemble diurnal climatologies with uncertainties shown in inter-quartile ranges.
plot_rsl(df_output[, var, fig, ax])	Produce a quick plot of RSL results

6.3.6. Roughness Calculations

Functions for calculating roughness parameters:

cal_z0zd(ser_qh, ser_ustar, ser_ta_c, ...[, ...])	Calculates surface roughness and zero plane displacement height.
cal_neutral(ser_qh, ser_ustar, ser_ta_c, ...)	Calculates the rows associated with neutral condition (threshold=0.01)

6.3.7. Attribution Analysis

Functions for decomposing near-surface variable changes into physically attributable components using Shapley value analysis [Owen, 1972, Shapley, 1953]. See Temperature Attribution Analysis for a worked example.

attribute(df_output_A, df_output_B[, variable])	Generic attribution function for near-surface variables.
diagnose(df_output[, variable])	Generic diagnostic function for near-surface variables.
attribute_t2(df_output_A, df_output_B, ...)	Decompose T2 differences between two SUEWS scenarios.
attribute_q2(df_output_A, df_output_B, ...)	Decompose q2 (2m specific humidity) differences between two SUEWS scenarios.
attribute_u10(df_output_A, df_output_B[, ...])	Decompose U10 (10m wind speed) differences between two SUEWS scenarios.
diagnose_t2(df_output, df_forcing[, method, ...])	Automatically identify anomalous T2 values and attribute the causes.
diagnose_q2(df_output, df_forcing[, method, ...])	Automatically identify anomalous q2 values and attribute the causes.
diagnose_u10(df_output[, method, threshold, ...])	Automatically identify anomalous U10 values and attribute the causes.
AttributionResult(variable, contributions, ...)	Container for attribution analysis results.