PlotResults API Reference

geoloop.plotting.create_plots.PlotResults

A class with functions for generating plots of simulation results. Different plots can be created for different types of simulations and models (e.g. single simulations, stochastic simulation, FINVOL model, ANALYTICAL model).

create_scatterplots staticmethod

create_scatterplots(
    results_df: DataFrame,
    params_df: DataFrame,
    y_variable: str,
    out_path: Path,
) -> None

Only compatible with results and inputs of stochastic (MC) simulations. Generates and saves scatter plots for all parameters in the simulations results, with y_variable on the y-axis. The parameters in the list of 'y_variable' are plotted against all other parameters in the results and input dataframes.

Parameters:

Name	Type	Description	Default
results_df	DataFrame	DataFrame containing simulation result parameters as columns.	required
params_df	DataFrame	DataFrame containing simulation input parameters as columns.	required
y_variable	str	The variable parameter to be plotted on the y-axis.	required
out_path	Path	Path to the directory where the plots will be saved.	required

Raises:

Type	Description
ValueError	If y_variable is not found in either results_df or param_df.

Returns:

Type	Description
None

create_timeseriesplot staticmethod

create_timeseriesplot(
    results_dfs: DataFrame | list[DataFrame],
    out_path: Path,
    plot_parameters: list,
)

Only compatible with (multiple) single simulations. Generates and saves a timeseries plot for various simulation results over time. Results of multiple single simulations can be plotted together.

Plot shows the generated power, flowrate, fluid inlet en outlet temperatures, depth-average borehole wall temperature, pumping pressure and required pumping power over time.

Parameters:

Name	Type	Description	Default
results_dfs	Union[DataFrame, List[DataFrame]]	DataFrame(s) containing simulation results.	required
out_path	Path	Directory where plots are saved.	required
plot_parameters	List[str]	List of variables to plot.	required

Raises:

Type	Description
ValueError	If any required parameter is missing from a DataFrame in results_dfs.

Returns:

Type	Description
None

create_depthplot staticmethod

create_depthplot(
    plot_parameters: list,
    times: list,
    params_ds: Dataset | list[Dataset],
    results_ds: Dataset | list[Dataset],
    out_path: Path,
)

Only compatible with (multiple) single simulations. Generates and saves depth-profiles at different timesteps in the simulation results, for fluid temperatures, borehole wall temperature, subsurface temperature, subsurface heat flow and subsurface bulk thermal conductivity.

Parameters:

Name	Type	Description	Default
plot_parameters	List[str]	List of parameters to plot.	required
times	List[float]	Simulation timesteps for which profiles are plotted.	required
params_ds	Union[Dataset, List[Dataset]]	Dataset(s) containing simulation input parameters.	required
results_ds	Union[Dataset, List[Dataset]]	Dataset(s) containing simulation results.	required
out_path	Path	Directory to save plots.	required

Raises:

Type	Description
ValueError	If any required parameter is missing from a DataFrame in results_ds or params_ds.

Returns:

Type	Description
None

create_borehole_temp_plot staticmethod

create_borehole_temp_plot(
    segindex: list[int],
    times: list,
    params_ds: Dataset | list[Dataset],
    results_ds: Dataset | list[Dataset],
    singlerun: SingleRun,
    out_path: Path,
)

Only compatible with (multiple) single simulations. Generates and saves depth-profiles at different timesteps in the simulation results, for fluid temperatures, borehole wall temperature, subsurface temperature, subsurface heat flow and subsurface bulk thermal conductivity.

Generate borehole cross-section temperature plots at different timesteps.

Parameters:

Name	Type	Description	Default
segindex	List[int]	Segment indices to plot.	required
times	List[float]	Timesteps to plot.	required
params_ds	Union[Dataset, List[Dataset]]	Dataset(s) containing simulation input parameters.	required
results_ds	Union[Dataset, List[Dataset]]	Dataset(s) containing simulation results.	required
singlerun	SingleRun	SingleRun object with simulation input parameters.	required
out_path	Path	Directory to save plots.	required

Raises:

Type	Description
ValueError	If any required parameter is missing from a DataFrame in results_ds or params_ds.

Returns:

Type	Description
None (the plots are saved directly to the specified output path).

create_barplot staticmethod

create_barplot(
    results_df: DataFrame | list[DataFrame],
    params_df: DataFrame | list[DataFrame],
    y_variable: str,
    outpath: Path,
) -> None

Only compatible with results and inputs of stochastic (MC) simulations. Generates and saves a tornado bar plot, that shows the correlation of a specified simulation parameter with other simulation input parameters and results.

This function merges simulation input parameters and results dataframes, calculates the correlation of the specified simulation parameter (y_variable) with the other parameters, and visualizes the sensitivity of the y_variable to changes in the other system parameters.

Parameters:

Name	Type	Description	Default
results_df	Union[DataFrame, List[DataFrame]]	Simulation result dataframe(s), contain(s) simulation result parameters as columns. Each DataFrame corresponds to a single simulation. It should include the columns 'samples' and 'file_name' for merging purposes.	required
params_df	Union[DataFrame, List[DataFrame]]	Simulation input dataframe(s), contain(s) simulation input parameters as columns. It should include the columns 'samples' and 'file_name' for merging purposes. The column 'k_s' will be renamed to 'k_s_par'.	required
y_variable	str	Variable to analyze sensitivity for. The simulation parameter (either input or result) to be plotted on the y-axis. Correlation with this parameter is visualized in the plot.	required
outpath	Path	Directory to save the plot.	required

Returns:

Type	Description
None (plots are saved directly to the specified output path)

Notes

• The function selects only the simulation (input and result) parameters with numeric values and with a non-zero standard deviation.
• If the specified y_variable does not exist in the merged DataFrame, no plot is created. No error is raised.

plot_temperature_field staticmethod

plot_temperature_field(
    time: int,
    temperature_result_da: DataArray,
    Tmin: float,
    Tmax: float,
    out_path: Path,
) -> None

Only compatible with results and numerical (FINVOL model) simulations. Generates and saves a plot of the calculated 3D (z=len(1)) temperature grid around the borehole, for a specific timestep.

Parameters:

Name	Type	Description	Default
time	int	Index of the timestep to create the plot for.	required
temperature_result_da	DataArray	Temperature DataArray, containing 3D (z=len(1)) grid of calculated temperature values around the borehole.	required
Tmin	float	Minimum temperature in the DataArray for color scaling.	required
Tmax	float	Maximum temperature in the DataArray for color scaling.	required
out_path	Path	Directory to save the plot.	required

Returns:

Type	Description
None (plots are saved directly to the specified output path)

create_temperature_field_movie staticmethod

create_temperature_field_movie(in_path: Path) -> None

Only compatible with results and numerical (FINVOL model) simulations. Generates and saves a clip of a sequence of the temperature grid plots creates using the method plot_temperature_field.

Parameters:

Name	Type	Description	Default
in_path	Path	Directory containing temperature field images.	required

Returns:

Type	Description
None (plots are saved directly to the specified output path)

extract_timestep staticmethod

extract_timestep(filename: str) -> float

Extracts timestep from the filename, used for the chronological ordering of temperature grid plots in the method create_temperature_field_movie.

Parameters:

Name	Type	Description	Default
filename	str	Name of the image file.	required

Returns:

Type	Description
float	Extracted timestep or infinity if not found.