Validation¶

class spy4cast.spy4cast.Validation(training_mca: MCA, validating_dsy: Preprocess, validating_dsz: Preprocess)¶

Bases: _Procedure

Perform validation methodology

Parameters:

training_mca (MCA) – MCA perform with the training datasets
validating_dsy (Preprocess) – Predictor field for validation
validating_dsz (Preprocess) – Predictand field for validation

Examples

Run the MCA with a training_predicting and a training_predictor field

>>> from spy4cast import Dataset, Region, Month
>>> from spy4cast.spy4cast import MCA, Preprocess
>>> t_y = Preprocess(Dataset("dataset_y.nc").open("y").slice(
...         Region(-50, 10, -50, 20, Month.JUN, Month.AUG, 1960, 1990)))
>>> t_z = Preprocess(Dataset("dataset_z.nc").open("z").slice(
...         Region(-30, 30, -120, 120, Month.DEC, Month.FEB, 1961, 1991)))
>>> mca = MCA(t_y, t_z, 3, 0.01)
>>> # Validate on the same data but with a different period
>>> v_y = Preprocess(Dataset("dataset_y.nc").open("y").slice(
...         Region(-50, 10, -50, 20, Month.JUN, Month.AUG, 2000, 2010)))
>>> v_z = Preprocess(Dataset("dataset_z.nc").open("z").slice(
...         Region(-30, 30, -120, 120, Month.DEC, Month.FEB, 2001, 2011)))
>>> val = Validation(mca, v_y, v_z)

All the Validation Variables easily accesioble

>>> cor = val.r_z_zhat_s_separated_modes.reshape((3, len(v_z.lat), len(v_z.lon)))  # 3 is the number of modes
>>> # Plot with any plotting library
>>> import matplotlib.pyplot as plt
>>> import cartopy.crs as ccrs
>>> fig = plt.figure()
>>> ax = fig.add_subplot(projection=ccrs.PlateCarree())
>>> ax.contourf(v_z.lon, v_z.lat, cor[0, :, :])
>>> ax.coastlines()

Save the data in .npy to use in a different run

>>> val.save("saved_validation_", folder="saved_data")

Reuse the previuosly ran data easily with one line

>>> val = Validation.load(
...     "saved_validation_", folder="saved_data",
...     validating_dsy=v_y, validating_dsz=v_z, training_mca=mca
... )  # IMPORTANT TO USE validating_dsy=, validating_dsz= and training_mca=

Plot with one line and several options

>>> # plot_type=pcolor to use pcolormesh, change the default cmap and figisze with a single option
>>> # halt_program=False does not halt execution and lets us create two plots at the same time: crossvalidation
>>> val.plot_zhat(1990, show_plot=True, halt_program=False, cmap="jet", figsize=(20, 10), plot_type="pcolor")
>>> val.plot(show_plot=True, halt_program=True, cmap="jet", figsize=(20, 10), plot_type="pcolor")

psi_accumulated_modes¶

Psi calculated with the training MCA data. Dimension: 1 x training_y_space x training_z_space

Type:: npt.NDArray[np.float32]

zhat_accumulated_modes¶

Zhat predicted for the predictand using all modes accumulated. Dimension: 1 x validating_z_space x validating_z_time

Type:: npt.NDArray[np.float32]

r_z_zhat_t_accumulated_modes¶

Correlation in time for accumlating all modes selected (nm) between z and zhat. Dimension: 1 x valudating_z_time

Type:: npt.NDArray[np.float32]

p_z_zhat_t_accumulated_modes¶

Pvalue of the correlation in time for accumlating all modes selected (nm) between z and zhat. Dimension: 1 x valudating_z_time

Type:: npt.NDArray[np.float32]

r_z_zhat_s_accumulated_modes¶

Correlation in space for accumlating all modes selected (nm) between z and zhat. Dimension: 1 x valudating_z_space

Type:: npt.NDArray[np.float32]

p_z_zhat_s_accumulated_modes¶

Pvalue of the correlation in space for accumlating all modes selected (nm) between z and zhat. Dimension: 1 x valudating_z_space

Type:: npt.NDArray[np.float32]

Attributes Summary

`training_mca`	Training mca used for validation
`validating_dsy`	Preprocessed dataset introduced as validating predictor
`validating_dsz`	Preprocessed dataset introduced as validating predictand
`var_names`	Returns the variables contained in the object

Methods Summary

`load`(prefix[, folder, zip_file, ...])	Load an Validation object from .npy files saved with Validation.save.
`plot`(*[, save_fig, show_plot, halt_program, ...])	Plot the Validation results
`plot_zhat`(year[, save_fig, show_plot, ...])	Plots the map of Zhat

Attributes Documentation

training_mca¶: Training mca used for validation

validating_dsy¶: Preprocessed dataset introduced as validating predictor

validating_dsz¶: Preprocessed dataset introduced as validating predictand

var_names¶: Returns the variables contained in the object

Methods Documentation

classmethod load(prefix: str, folder: str = '.', zip_file: str | None = None, *, validating_dsy: Preprocess | None = None, validating_dsz: Preprocess | None = None, training_mca: MCA | None = None, **attrs: Any) → Validation¶

Load an Validation object from .npy files saved with Validation.save.

Parameters:

prefix (str) – Prefix of the files containing the information for the object
folder (str) – Directory of the files
zip_file (optional, str) – If provided folder will be searched inside of the zip file, that should conatin all the data.
validating_dsy (Preprocess) – ONLY KEYWORD ARGUMENT. Preprocessed dataset of the validating predictor variable
validating_dsz (Preprocess) – Preprocessed dataset of the validating predicting variable
training_mca (MCA) – ONLY KEYWORD ARGUMENT. Training mca

Return type:

Validation

Examples

Load with Validation.load using the same validating datsets and training mca as when the methodology was run

>>> val = Validation.load(
...     "saved_validation_", folder="saved_data",
...     validating_dsy=validating_y, validating_dsz=validating_z, training_mca=validating_mca
... )  # IMPORTANT TO USE validating_dsy=, validating_dsz= and training_mca=

Save: on a previous run the validation is calcuated

>>> from spy4cast import Dataset, Region, Month
>>> from spy4cast.spy4cast import Validation, MCA, Preprocess
>>> t_y = Preprocess(Dataset("dataset_y.nc").open("y").slice(
...         Region(-50, 10, -50, 20, Month.JUN, Month.AUG, 1960, 1990)))
>>> t_z = Preprocess(Dataset("dataset_z.nc").open("z").slice(
...         Region(-30, 30, -120, 120, Month.DEC, Month.FEB, 1961, 1991)))
>>> training_mca = MCA(t_y, t_z, 3, 0.01)
>>> # Validate on the same data but with a different period
>>> validating_y = Preprocess(Dataset("dataset_y.nc").open("y").slice(
...         Region(-50, 10, -50, 20, Month.JUN, Month.AUG, 2000, 2010)))
>>> validating_z = Preprocess(Dataset("dataset_z.nc").open("z").slice(
...         Region(-30, 30, -120, 120, Month.DEC, Month.FEB, 2001, 2011)))
>>> val = Validation(training_mca, validating_y, validating_z)
>>> val.save("saved_validation_", folder="data")  # Save the output

Load: To avoid running the methodology again for plotting and analysis load the data directly

>>> from spy4cast import Dataset, Region, Month
>>> from spy4cast.spy4cast import Validation, MCA, Preprocess
>>> t_y = Preprocess(Dataset("dataset_y.nc").open("y").slice(
...         Region(-50, 10, -50, 20, Month.JUN, Month.AUG, 1960, 1990)))
>>> t_z = Preprocess(Dataset("dataset_z.nc").open("z").slice(
...         Region(-30, 30, -120, 120, Month.DEC, Month.FEB, 1961, 1991)))
>>> training_mca = MCA(t_y, t_z, 3, 0.01)
>>> # Validate on the same data but with a different period
>>> validating_y = Preprocess(Dataset("dataset_y.nc").open("y").slice(
...         Region(-50, 10, -50, 20, Month.JUN, Month.AUG, 2000, 2010)))
>>> validating_z = Preprocess(Dataset("dataset_z.nc").open("z").slice(
...         Region(-30, 30, -120, 120, Month.DEC, Month.FEB, 2001, 2011)))
>>> val = Validation.load("saved_validation_", "data",
...     training_mca=training_mca, validating_y=validating_y, validating_y=validating_z)

Then you can plot as usual

>>> val.plot(save_fig=True, name="cross.png")
>>> val.plot_zhat(2004, save_fig=True, name="zhat_1999.png")

plot(*, save_fig: bool = False, show_plot: bool = False, halt_program: bool = False, folder: str | None = None, name: str | None = None, cmap: str | None = None, map_ticks: ndarray[Any, dtype[float32]] | Sequence[float] | None = None, map_levels: ndarray[Any, dtype[float32]] | Sequence[float] | bool | None = None, version: Literal['default', 2] = 'default', mca: MCA | None = None, figsize: Tuple[float, float] | None = None, nm: int | None = None, plot_type: Literal['contour', 'pcolor'] = 'contour') → Tuple[Tuple[Figure], Tuple[Tuple[Axes, ...]]]¶

Plot the Validation results

Parameters:

save_fig – Saves the fig using folder and name parameters
show_plot – Shows the plot
halt_program – Only used if show_plot is True. If True shows the plot if plt.show and stops execution. Else uses fig.show and does not halt program
folder – Directory to save fig if save_fig is True
name – Name of the fig saved if save_fig is True
cmap – Colormap for the predicting maps
map_ticks – Ticks for the z map in version default
map_levels – Levels for the z map in version default
version – Select version from: default and 2
mca – MCA results for version 2
figsize – Set figure size. See plt.figure
nm (int, optional) – Number of modes to use for the corssvalidation plot. Must be less than or equal to nm used to run the methodology. If -1 use all modes.
plot_type ({"contour", "pcolor"}, defaut = "pcolor") – Plot type. If contour it will use function ax.contourf, if pcolor ax.pcolormesh.

Returns:

Tuple[plt.Figure] – Figures object from matplotlib
Tuple[Tuple[plt.Axes]] – Tuple of axes in figure

Examples

Plot and halt the program

>>> val.plot(show_plot=True, halt_program=True)

Save the plot

>>> val.plot(save_fig=True, name="val_plot.png")

Plot with pcolormesh and be precise with the resolution

>>> val.plot(save_fig=True, name="val.png", plot_type="pcolor")

Plot and not halt the program

>>> val.plot(show_plot=True)
>>> # .... Compute a new validation for example
>>> import matplotlib.pyplot as plt
>>> plt.show()  # Will show the previously ran plot

Plots the map of Zhat

Parameters:

save_fig – Saves the fig using folder and name parameters
show_plot – Shows the plot
halt_program – Only used if show_plot is True. If True shows the plot if plt.show and stops execution. Else uses fig.show and does not halt program
year – Year (or years) to plot
folder – Directory to save fig if save_fig is True
name – Name of the fig saved if save_fig is True
cmap – Colormap for the predicting map
y_ticks – Ticks for the y map
z_ticks – Ticks for the z map
y_levels – Levels for the map y
z_levels – Levels for the map z
figsize – Set figure size. See plt.figure
plot_type ({"contour", "pcolor"}, defaut = "pcolor") – Plot type. If contour it will use function ax.contourf, if pcolor ax.pcolormesh.

Returns:

plt.Figure – Figure object from matplotlib
Sequence[plt.Axes] – Tuple of axes in figure

Examples

Plot a year prediction

>>> val.plot_zhat(1990, show_plot=True, halt_program=True, save_fig=True, name="zhat_1990.png")