Preprocess¶

class spy4cast.spy4cast.Preprocess(ds: Dataset, order: int | None = None, period: float | None = None, freq: Literal['high', 'low'] = 'high', detrend: bool = False, group_season: bool = True)¶

Bases: _Procedure

Preprocess variables for MCA and Crossvalidation: anomaly and reshaping

Parameters:

ds (Dataset) – Dataset to preprocess
order (optional, int) – If specified as well as period, a butterworth filter with those parameters will be applied
period (optional, float) – If specified as well as period, a butterworth filter with those parameters will be applied
freq ({'high', 'low'}, default = 'high') – If specified as well as period, a butterworth filter with those parameters will be applied
detrend (bool, default = False) – Apply scipy.signal.detrend on the time axis.
group_season (bool, default=True) – If True, group data points with the same season_id (defined below) and take the average. This creates a new dataset with only time dimension being season_id. This dataset is the one used to calculate anomalies. This is used when regions span multiple months (e.g. JUN-AUG) and you consider the mean during this season the variable. If you are using daily data set this setting to False so that it preserves the day in the time variable. season_id is the common year of the region; or for regions like DEC-FEB that mix years, the year of the end of the region (FEB).

Examples

Preprocess a dataset with one line

>>> from spy4cast import Dataset, Region, Month
>>> from spy4cast.spy4cast import Preprocess
>>> ds = Dataset("dataset.nc").open("sst").slice(
...     Region(-40, 40, -20, 20, Month.JAN, Month.MAR, 1940, 2000))
>>> y = Preprocess(ds)

Add a butterworth filter

>>> y = Preprocess(ds, period=12, order=4)

Detrend

>>> y = Preprocess(ds, detrend=True)

Acces all the Preprocess Variables easily

>>> data = y.data.reshape((len(y.lat), len(y.lon), len(y.time)))
>>> # 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, data[:, :, 0])
>>> ax.coastlines()
>>> plt.show()

Save the preprocess in a file to use later

>>> y.save("sst_preprocessed_", folder="saved_data")

Avoid loading the dataset and work with the preprocessed data directly

>>> y = Preprocess.load("sst_preprocessed_", folder="saved_data")

Plot a map with just one line to visualize the anomaly

>>> y.plot(1990, show_plot=True, halt_program=True)

Attributes Summary

`data`	Raw data in the object with nan as in the original dataset.
`ds`	Dataset that has been preprocessed.
`land_data`	Data but organised in a land array.
`lat`	Latitude coordinate of the variable in degrees ranging from -90 to 90
`lon`	Longitude coordinate of the data in degrees ranging from -180 to 180
`meta`	Returns a np.ndarray containg information about the preprocessed dataset.
`region`	Region used to slice the original dataset
`shape`	Shape of the data as a tuple of space x time
`time`	Time coordinate of the data.
`var`	Name of the variable of the dataset that was preprocessed.
`var_names`	Returns the variables contained in the object (data, time, lat, lon, ...)

Methods Summary

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

Plot the preprocessed data for spy4cast methodologes

Attributes Documentation

data¶: Raw data in the object with nan as in the original dataset. It has dimensions of space x time. Should be reshaped like: data.reshape((nlat, nlon, ntime))

ds¶: Dataset that has been preprocessed. On loaded preprocess this raises an error

land_data¶: Data but organised in a land array. This includes a mask that indicates where the land is in the dataset by masking the nan values. This is useful when handling variables like sea surface temperature

lat¶: Latitude coordinate of the variable in degrees ranging from -90 to 90

lon¶: Longitude coordinate of the data in degrees ranging from -180 to 180

meta¶

Returns a np.ndarray containg information about the preprocessed dataset. It includes the region and the variable

First 9 values is region as numpy, then variable as str

region¶: Region used to slice the original dataset

shape¶: Shape of the data as a tuple of space x time

time¶: Time coordinate of the data.

var¶: Name of the variable of the dataset that was preprocessed.

var_names¶: Returns the variables contained in the object (data, time, lat, lon, …)

Methods Documentation

Plot the preprocessed data for spy4cast methodologes

Parameters:

selected_year – Deprecated: same as year
year – Plot the anomaly map for the last date of the season with this year
timestamp – Plot the date which is closest to the timestamp
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
cmap – Colormap for the map
folder – Directory to save fig if save_fig is True
name – Name of the fig saved if save_fig is True
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.
levels – Levels for the map

Examples

Plot the anomaly on any year of the dataset

>>> y = Preprocess(Dataset("dataset_y.nc").open("y").slice(
...         Region(-50, 10, -50, 20, Month.JUN, Month.AUG, 1960, 2010)))
>>> # Plot 1990, 1991, 1992 and save 1990
>>> y.plot(selected_year=1990, show_plot=True, save_fig=True, name='y_1990.png')
>>> y.plot(selected_year=1991, show_plot=True, cmap='viridis')  # Change the default color map
>>> y.plot(selected_year=1992, show_plot=True, halt_program=True)  # halt_program lets you show multiple figures at the same time

Returns:

figures (Tuple[plt.Figure]) – Figures objects from matplotlib. In this case just one figure with one axes
ax (Tuple[Tuple[plt.Axes]]) – Tuple of axes in figure. In this case just one axes