Crossvalidation

class spy4cast.spy4cast.Crossvalidation(dsy: Preprocess | PreprocessUnstructured, dsz: Preprocess | PreprocessUnstructured, nm: int, alpha: float, multiprocessed: bool = False, sig: Literal['test-t', 'monte-carlo'] = 'test-t', montecarlo_iterations: int | None = None, num_svdvals: int | None = None, fold_size: int = 1)

Bases: _Procedure

Perform crossvalidation methodology

Parameters:

  • dsy (Preprocess, PreprocessUnstructured) – Predictor field

  • dsz (Preprocess, PreprocessUnstructured) – Predictand field

  • nm (int) – Number of modes

  • alpha (float) – Significance coeficient

  • multiprocessed (bool) – Use multiprocessing for the methodology

  • sig ({'monte-carlo', 'test-t'}) – Signification technique: monte-carlo or test-t

  • num_svdvals (int or None, default=None) – If not None, approximate the sum of the singular values of the covariance matrix (used to calculate scf) to the sum of the largest num_svdvals singular values. Useful to speed up MCA if the scf is not needed or it is not needed to be precise.

  • fold_size (int, default = 1) – By default crossvalidation is run by removing one year and calculate the modes using MCA with the rest of the data. Then, the removed year is predicted using those modes. You can change fold_size to remove a different amount of years from the data. For example, if fold_size = 4 4 years are removed at each iteratorion, MCA is calculated with the rest and those 4 year are calculated with the obtained modes. Then the process continues with next 4 years. If the data had 12 years, 3 iterations will be needed.

Examples

Run the methodology with a predicting and a predictor field

>>> from spy4cast import Dataset, Region, Month
>>> from spy4cast.spy4cast import MCA, Preprocess
>>> y = Preprocess(Dataset("dataset_y.nc").open("y").slice(
...         Region(-50, 10, -50, 20, Month.JUN, Month.AUG, 1960, 2010)))
>>> z = Preprocess(Dataset("dataset_z.nc").open("z").slice(
...         Region(-30, 30, -120, 120, Month.DEC, Month.FEB, 1961, 2011)))
>>> map_y = Preprocess(Dataset("dataset_y.nc").open("y").slice(
...         Region(-80, 30, -70, 50, Month.JUN, Month.AUG, 1960, 2010)))
>>> map_z = Preprocess(Dataset("dataset_z.nc").open("z").slice(
...         Region(-60, 60, -150, 150, Month.DEC, Month.FEB, 1961, 2011)))
>>> mca = MCA(y, z, 3, 0.01)

All the Crossvalidation Variables easily accesioble

>>> cor = cross.r_z_zhat_s_separated_modes.reshape((3, len(z.lat), len(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(z.lon, z.lat, cor[0, :, :])
>>> ax.coastlines()

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

>>> cross.save("saved_cross_", folder="saved_data")

Reuse the previuosly ran data easily with one line

>>> cross = Crossvalidation.load("saved_cross_", folder="saved_data", dsy=y, dsz=z)  # IMPORTANT TO USE dsy= and dsz=

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
>>> cross.plot_zhat(1990, show_plot=True, halt_program=False, cmap="jet", figsize=(20, 10), plot_type="pcolor")
>>> cross.plot(show_plot=True, halt_program=True, cmap="jet", figsize=(20, 10), plot_type="pcolor")
zhat_separated_modes

Hindcast of field to predict using crosvalidation for each individual mode. Dimensions: nm x nz x nt

Type:

numpy.ndarray[Any, numpy.dtype[numpy.float32]]

zhat_accumulated_modes

Hindcast of field to predict using crosvalidation for n modes (1, 1->2, …, 1->nm) Dimensions: nm x nz x nt

Type:

numpy.ndarray[Any, numpy.dtype[numpy.float32]]

scf

Squared covariance fraction of the mca for each mode Dimensions: nm x nt

Type:

numpy.ndarray[Any, numpy.dtype[numpy.float32]]

r_z_zhat_t_separated_modes

Correlation between zhat and Z for each time (time series) for each individual mode Dimensions: nm x nt

Type:

numpy.ndarray[Any, numpy.dtype[numpy.float32]]

r_z_zhat_t_accumulated_modes

Correlation between zhat and Z for each time (time series) for n modes (1, 1->2, …, 1->nm) Dimensions: nm x nt

Type:

numpy.ndarray[Any, numpy.dtype[numpy.float32]]

p_z_zhat_t_separated_modes

P values of r for each individual mode Dimensions: nm x nt

Type:

numpy.ndarray[Any, numpy.dtype[numpy.float32]]

p_z_zhat_t_accumulated_modes

P values of rt for n modes (1, 1->2, …, 1->nm) Dimensions: nm x nt

Type:

numpy.ndarray[Any, numpy.dtype[numpy.float32]]

r_z_zhat_s_separated_modes

Correlation between time series (for each point) of zhat and z (map) for each individual mode Dimensions: nm x nz

Type:

numpy.ndarray[Any, numpy.dtype[numpy.float32]]

r_z_zhat_s_accumulated_modes

Correlation between time series (for each point) of zhat and z (map) for n modes (1, 1->2, …, 1->nm) Dimensions: nm x nz

Type:

numpy.ndarray[Any, numpy.dtype[numpy.float32]]

p_z_zhat_s_separated_modes

P values of rr for each individual mode Dimensions: nm x nz

Type:

numpy.ndarray[Any, numpy.dtype[numpy.float32]]

p_z_zhat_s_accumulated_modes

P values of rr for n modes (1, 1->2, …, 1->nm) Dimensions: nm x nz

Type:

numpy.ndarray[Any, numpy.dtype[numpy.float32]]

r_uv

Correlation score betweeen u and v for each mode Dimensions: nm x nt

Type:

numpy.ndarray[Any, numpy.dtype[numpy.float32]]

r_uv_sig

Correlation score betweeen u and v for each mode where significative Dimensions: nm x nt

Type:

numpy.ndarray[Any, numpy.dtype[numpy.float32]]

p_uv

P value of ruv Dimensions: nm x nt

Type:

numpy.ndarray[Any, numpy.dtype[numpy.float32]]

suy

Correlation in space of the predictor with the singular vector. Dimensions: ny x nt x nm

Type:

numpy.ndarray[Any, numpy.dtype[numpy.float32]]

suz

Correlation in space of the predictand with the singular vector. Dimensions: nz x nt x nm

Type:

numpy.ndarray[Any, numpy.dtype[numpy.float32]]

suy_sig

Correlation in space of the predictor with the singular vector where pvalue is smaller than alpha. Dimensions: ny x nt x nm

Type:

numpy.ndarray[Any, numpy.dtype[numpy.float32]]

suz_sig

Correlation in space of the predictand with the singular vector where pvalue is smaller than alpha. Dimensions: nz x nt x nm

Type:

numpy.ndarray[Any, numpy.dtype[numpy.float32]]

us

Singular vectors of the predictor field. Dimensions: nm x nt x nt

Type:

numpy.ndarray[Any, numpy.dtype[numpy.float32]]

vs

Singular vectors of the predictand field. Dimensions: nm x nt x nt

Type:

numpy.ndarray[Any, numpy.dtype[numpy.float32]]

alpha

Correlation factor

Type:

float

Attributes Summary

dsy

Preprocessed dataset introduced as predictor

dsz

Preprocessed dataset introduced as predictand

var_names

Returns the variables contained in the object (scf, us, vs, r_uv, ...)

Methods Summary

load(prefix[, folder, zip_file, dsz, dsy])

Load an Crossvalidation object from .npy files saved in Crossvalidation.save.

plot(*[, save_fig, show_plot, halt_program, ...])

Plot the Crossvalidation results

plot_zhat(year[, save_fig, show_plot, ...])

Plots the map of Zhat

Attributes Documentation

dsy

Preprocessed dataset introduced as predictor

dsz

Preprocessed dataset introduced as predictand

var_names

Returns the variables contained in the object (scf, us, vs, r_uv, …)

Methods Documentation

classmethod load(prefix: str, folder: str = '.', zip_file: str | None = None, *, dsz: Preprocess | PreprocessUnstructured | None = None, dsy: Preprocess | PreprocessUnstructured | None = None, **attrs: Any) → Crossvalidation

Load an Crossvalidation object from .npy files saved in Crossvalidation.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.

  • dsy (Preprocess, PreprocessUnstructured) – ONLY KEYWORD ARGUMENT. Preprocessed dataset of the predictor variable

  • dsz (Preprocess, PreprocessUnstructured) – ONLY KEYWORD ARGUMENT. Preprocessed dataset of the predicting variable

Return type:

Crossvalidation

Examples

Load with just one line

>>> cross = Crossvalidation.load(prefix="cross_", folder="saved_data")

Save: on a previous run the crossvalidation is calcuated

>>> from spy4cast import Dataset, Region, Month
>>> from spy4cast.spy4cast import Crossvalidation, Preprocess
>>> y = Preprocess(Dataset("dataset_y.nc").open("y").slice(
...         Region(-50, 10, -50, 20, Month.JUN, Month.AUG, 1960, 2010)))
>>> z = Preprocess(Dataset("dataset_z.nc").open("z").slice(
...         Region(-30, 30, -120, 120, Month.DEC, Month.FEB, 1961, 2011)))
>>> cross = Crossvalidation(y, z, 3, 0.01)
>>> cross.save("saved_cross_", folder="data")  # Save the output

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

>>> from spy4cast.spy4cast import Crossvalidation, Preprocess
>>> from spy4cast import Dataset, Region, Month
>>> y = Preprocess(Dataset("dataset_y.nc").open("y").slice(
...         Region(-50, 10, -50, 20, Month.JUN, Month.AUG, 1960, 2010)))  # YOU SHOULD USE THE SAME REGION
>>> z = Preprocess(Dataset("dataset_z.nc").open("z").slice(
...         Region(-30, 30, -120, 120, Month.DEC, Month.FEB, 1961, 2011)))
>>> cross = Crossvalidation.load("saved_cross_", folder="data", dsy=y, dsz=z)  # IMPORTANT TO USE dsy= and dsz=

Then you can plot as usual

>>> cross.plot(save_fig=True, name="cross.png")
>>> cross.plot_zhat(1999, 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, central_longitude_z: float | None = None, z_xlim: Tuple[float, float] | None = None, ts_only_sig: bool = False, rmse_only_sig: bool = False, nm: int | None = None, plot_type: Literal['contour', 'pcolor', 'tricontour', 'scatter'] | None = None, rmse_levels: ndarray[Any, dtype[float32]] | Sequence[float] | bool | None = None) → Tuple[Tuple[Figure], Tuple[Tuple[Axes, ...]]]

Plot the Crossvalidation results

Parameters:

  • save_fig – Saves the fig using folder and name parameters

  • show_plot – Shows the plot but does NOT stop the program. Calls fig.show. If you want the behaviour of plt.plot add the halt_program option.

  • 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.

  • ts_only_sig (bool, default = False) – If Ture, time series for the ACC map only takes into account the region where ACC is significant

  • rmse_only_sig (bool, default = False) – If Ture, RMSE map only takes into account the region where ACC is significant

  • plot_type ({"contour", "pcolor", "tricontour", "scatter"}, default = "contour" or "scatter") – Plot type. If Z if of type Preprocess: contour it will use function ax.contourf, pcolor will use ax.pcolormesh. If Z if type PreprocessUnstructured, tricontour will use ax.tricontourf, scatter ax.scatter.

  • central_longitude_z (float, optional) – Longitude used to center the z map

  • z_xlim (tuple[float, float], optional) – Xlim lim for the z map passed into ax.set_extent

  • rmse_levels – Levels for the rmse map in version default

Returns:

  • figures (Tuple[plt.Figure]) – Figures objects from matplotlib. In this case just one figure

  • ax (Tuple[Tuple[plt.Axes]]) – Tuple of axes in figure. In the default case: 2 axes

Examples

Plot and halt the program

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

Save the plot

>>> cross.plot(save_fig=True, name="cross_plot.png")

Plot with pcolormesh and be precise with the resolution

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

Plot cross result in a bigger region

>>> from spy4cast import Dataset, Region, Month
>>> from spy4cast.spy4cast import Crossvalidation, Preprocess
>>> y = Preprocess(Dataset("dataset_y.nc").open("y").slice(
...         Region(-50, 10, -50, 20, Month.JUN, Month.AUG, 1960, 2010)))
>>> z = Preprocess(Dataset("dataset_z.nc").open("z").slice(
...         Region(-30, 30, -120, 120, Month.DEC, Month.FEB, 1961, 2011)))
>>> map_y = Preprocess(Dataset("dataset_y.nc").open("y").slice(
...         Region(-80, 30, -70, 50, Month.JUN, Month.AUG, 1960, 2010)))
>>> map_z = Preprocess(Dataset("dataset_z.nc").open("z").slice(
...         Region(-60, 60, -150, 150, Month.DEC, Month.FEB, 1961, 2011)))
>>> cross = Crossvalidation(y, z, 3, 0.01)
>>> cross.plot(show_plot=True, halt_program=True, map_y=map_y, map_z=map_z)

Plot and not halt the program

>>> cross.plot(show_plot=True)
>>> # .... Compute crossvalidation for example
>>> import matplotlib.pyplot as plt
>>> plt.show()  # Will show the previously ran plot
plot_zhat(year: int | List[int], save_fig: bool = False, show_plot: bool = False, halt_program: bool = False, folder: str | None = None, name: str | None = None, cmap: str = 'bwr', y_ticks: ndarray[Any, dtype[float32]] | Sequence[float] | None = None, z_ticks: ndarray[Any, dtype[float32]] | Sequence[float] | None = None, y_levels: ndarray[Any, dtype[float32]] | Sequence[float] | bool | None = None, z_levels: ndarray[Any, dtype[float32]] | Sequence[float] | bool | None = None, figsize: Tuple[float, float] | None = None, plot_type_y: Literal['contour', 'pcolor', 'tricontour', 'scatter'] | None = None, plot_type_z: Literal['contour', 'pcolor', 'tricontour', 'scatter'] | None = None) → Tuple[Figure, Tuple[Axes, Axes, Axes]]

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_y ({"contour", "pcolor", "tricontour", "scatter"}, default = "contour" or "scatter") – Plot type. If Y if of type Preprocess: contour it will use function ax.contourf, pcolor will use ax.pcolormesh. If Y if type PreprocessUnstructured, tricontour will use ax.tricontourf, scatter ax.scatter.

  • plot_type_z ({"contour", "pcolor", "tricontour", "scatter"}, default = "contour" or "scatter") – Plot type. If Z if of type Preprocess: contour it will use function ax.contourf, pcolor will use ax.pcolormesh. If Z if type PreprocessUnstructured, tricontour will use ax.tricontourf, scatter ax.scatter.

Examples

Plot a year prediction

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

  • figure (plt.Figure) – Figure object from matplotlib. In this case just one

  • axes (Sequence[plt.Axes]) – Tuple of axes in figure. In this case 3: y, z and zhat