MCA¶

class spy4cast.spy4cast.MCA(dsy: Preprocess | PreprocessUnstructured, dsz: Preprocess | PreprocessUnstructured, nm: int, alpha: float, sig: Literal['test-t', 'monte-carlo'] = 'test-t', montecarlo_iterations: int | None = None, num_svdvals: int | None = None)¶

Bases: _Procedure

Maximum covariance analysis between y (predictor) and Z (predictand)

Parameters:

dsy (Preprocess, PreprocessUnstructured) – Predictor
dsz (Preprocess, PreprocessUnstructured) – Predictand
nm (int) – Number of modes
alpha (float) – Significance level
sig ({'monte-carlo', 'test-t'}) – Signification technique: monte-carlo or test-t
montecarlo_iterations (optional, int) – Number of iterations for monte-carlo sig
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.

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 MCA Variables easily accesioble

>>> y_regression = mca.RUY.reshape((len(y.lat), len(y.lon), 6))  # 6 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(y.lon, y.lat, y_regression[:, :, 0])
>>> ax.coastlines()

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

>>> mca.save("saved_mca_", folder="saved_data")

Reuse the previuosly ran data easily with one line

>>> mca = MCA.load("saved_mca_", folder="saved_data", dsy=y, dsz=z)  # IMPORTANT TO USE dsy= and dsz=

Plot with one line and several options

>>> mca.plot(show_plot=True, halt_program=True, cmap="jet", figsize=(20, 10))

psi¶: Regression coefficient of the MCA model, so that ZHAT = PSI * Y

r, sigma, q: Singular vectors, and values

RUY¶

Correlation of the predictor field. Dimension: y_space x nm

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

RUY_sig¶

Correlation of the predictor field where pvalue is smaller than alpha. Dimension: y_space x nm

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

SUY¶

Regression in space of the predictor with the singular vector. Dimension: y_space x nm

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

SUY_sig¶

Regression in space of the predictor with the singular vector where pvalue is smaller than alpha. Dimension: y_space x nm

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

RUZ¶

Correlation of the predictand field. Dimension: z_space x nm

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

RUZ_sig¶

Correlation of the predictand field where pvalue is smaller than alpha. Dimension: z_space x nm

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

SUZ¶

Regression in space of the predictand with the singular vector. Dimension: z_space x nm

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

SUZ_sig¶

Regression in space of the predictand with the singular vector where pvalue is smaller than alpha. Dimension: z_space x nm

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

pvalruy¶

Pvalue of the correlation of the predictor field. Dimension: y_space x nm

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

pvalruz¶

Pvalue of the correlation of the predictand field. Dimension: z_space x nm

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

Us¶

Singular vectors of the predictor field. Dimension: nm x time

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

Vs¶

Singular vectors of the predictand field. Dimension: nm x time

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

scf¶

Square covariance fraction of the singular values. Dimension: nm

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

alpha¶

Significance coeficient.

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 (RUY, SUY, scf, ...)

Methods Summary

`from_land_arrays`(y, z, nm, alpha[, sig, ...])	Alternative constructor for mca that takes Land Array
`load`(prefix[, folder, zip_file, dsy, dsz])	Load an MCA object from .npy files saved in MCA.save.
`plot`(*[, save_fig, show_plot, halt_program, ...])	Plot the MCA results

Attributes Documentation

dsy¶: Preprocessed dataset introduced as predictor

dsz¶: Preprocessed dataset introduced as predictand

var_names¶: Returns the variables contained in the object (RUY, SUY, scf, …)

Methods Documentation

classmethod from_land_arrays(y: LandArray, z: LandArray, nm: int, alpha: float, sig: Literal['test-t', 'monte-carlo'] = 'test-t', montecarlo_iterations: int | None = None, num_svdvals: int | None = None) → MCA¶

Alternative constructor for mca that takes Land Array

Parameters:

y (LandArray) – Predictor (space x time)
z (LandArray) – Predictand (space x time)
nm (int) – Number of modes
alpha (alpha) – Significance level
sig ('monte-carlo or 'test-t') – Signification technique: monte-carlo or test-t
montecarlo_iterations (optional, int) – Number of iterations for monte-carlo sig
num_svdvals (int or None, default=None) – If True, 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.

Returns:

MCA object with the methodology performed

Return type:

MCA

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

MCA

Examples

Load with just one line

>>> mca = MCA.load(prefix="mca_", folder="saved_data")

Save: on a previous run the MCA is calcuated

>>> 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)))
>>> mca = MCA(y, z, 3, 0.01)
>>> mca.save("saved_mca_", folder="data")  # Save the output

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

>>> from spy4cast.spy4cast import MCA, 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)))
>>> mca = MCA.load("saved_mca_", folder="data", dsy=y, dsz=z)  # IMPORTANT TO USE dsy= and dsz=

Then you can plot as usual

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

Plot the MCA 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
cmap – Colormap for the predicting maps
signs – Sequence of True or False values of same length as nm. Where True the mode output will be multipled by -1.
folder – Directory to save fig if save_fig is True
name – Name of the fig saved if save_fig is True
y_ticks – Ticks for the maps of the Y output
z_ticks – Ticks for the maps of the Z output
y_levels – Levels for the maps of the Y output
z_levels – Levels for the maps of the Z output
figsize – Set figure size. See plt.figure
nm (int) – Number of modes to plot
map_y (Preprocess, PreprocessUnstructured) – Y to plot the map
map_z (Preprocess, PreprocessUnstructured) – Z to plot the map
rect_color ((r, g, b) or string, default = "r") – Color of the rectangle when using map_y and map_z that outlines the region where the methodology was originally ran
sig ({"monte-carlo", "test-t"}) – Significance method when map_y or map_z is set
montecarlo_iterations (int) – when monte-carlo sig and map_y or map_z is set
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.
height_ratios (list[float], optional) – Height ratios passed in to matplotlib.gridspec.Gridspec
width_ratios (list[float], optional) – Width ratios passed in to matplotlib.gridspec.Gridspec
central_longitude_y (float, optional) – Longitude used to center the y map
central_longitude_z (float, optional) – Longitude used to center the z map
y_xlim (tuple[float, float], optional) – Xlim for the y map passed into ax.set_extent
z_xlim (tuple[float, float], optional) – Xlim for the z map passed into ax.set_extent
variable ({"s", "r"}, default="r") – If “r”, plot RUY and RUZ (correlation) If “s”, plot SUY and SUZ (regression)

Note

ruy_ticks, ruz_ticks, ruy_levels and ruz_levels are deprecated

Returns:

figures (Tuple[plt.Figure]) – Figures objects from matplotlib. One figure per page of MCA with 3 modes per page
ax (Tuple[Tuple[plt.Axes]]) – Tuple of axes in figure. In this case 3 axes per mode: Us/Vs, Y, Z

Examples

Plot and halt the program

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

Save the plot

>>> mca.plot(save_fig=True, name="mca_plot.png")

Plot with pcolormesh and be precise with the resolution

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

Plot MCA result in a bigger region

>>> 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)
>>> mca.plot(show_plot=True, halt_program=True, map_y=map_y, map_z=map_z)

Plot and not halt the program

>>> mca.plot(show_plot=True)
>>> # .... Compute crossvalidation for example
>>> import matplotlib.pyplot as plt
>>> plt.show()  # Will show the previously ran plot