Tutorial¶

Spy4Cast offers a frontend to manage datasets in .nc format in python

Open¶

You can open a dataset really easily with a line of code using the Dataset interface:

from spy4cast import Dataset

DIR = "data/"  # If no dir is specified it look sin the current directory
NAME = "dataset.nc"
VAR = "sst"  # Variable to use in the dataset. For example `sst`
ds = Dataset(NAME, dir=DIR).open(VAR)

Slice¶

Most of the times you would like to slice a region of the dataset. You will need to use Region and Month for that:

from spy4cast import Dataset, Month, Region  # --- new --- #

DIR = "data/"
NAME = "dataset.nc"
VAR = "sst"  # Variable to use in the dataset. For example `sst`
ds = Dataset(NAME, dir=DIR).open(VAR)

# --- new --- #

# Latitulde goes from -90 to 90 and longitude form -180 to 180.
# If the dataset you use doesn't work like that and longiutde
# goes from 0 to 360 when you open the dataset this will be
# changed so you ALWAYS have to latitude from -90 to 90
# and longitude form -180 to 180
region = Region(
    lat0=-45,
    latf=0,
    lon0=-6,
    lonf=40,
    month0=Month.DEC,
    monthf=Month.MAR,
    # If the initial month is bigger than the final month (DEC --> MAR)
    # the dataset uses the year before for the initial month (1874 in thiss case)
    year0=1875,
    yearf=1990,
)
ds.slice(region)

# You can also do this in one line like: ds = Dataset(NAME, dir=DIR).open(VAR).slice(region)

Save¶

Every methodology can be saved for future usage (.save(“prefix_”, dir=’saved_data_directory’))

from spy4cast import Dataset, Region, Month
from spy4cast.spy4cast import Preprocess

DIR = "data/"
NAME = "dataset.nc"
VAR = "sst"  # Variable to use in the dataset. For example `sst`
ds = Dataset(NAME, dir=DIR).open(VAR).slice(
    Region(-90, 90, -180, 180, Month.JAN, Month.MAR, 1870, 1995)
)
preprocesed = Preprocess(ds)
preprocesed.save('save_preprocess_', dir='saved')

from spy4cast import Dataset, Region, Month
from spy4cast.meteo import Clim

DIR = "data/"
NAME = "dataset.nc"
VAR = "sst"  # Variable to use in the dataset. For example `sst`
ds = Dataset(NAME, dir=DIR).open(VAR).slice(
    Region(-90, 90, -180, 180, Month.JAN, Month.MAR, 1870, 1995)
)
clim = Clim(ds, 'map')  # You can plot a time series with Clim(ds, 'ts')
clim.plot(show_plot=True, save_fig=True, cmap='jet', dir='plots', name='plot.png')
# --- new --- #
clim.save('save_clim_', dir='saved')

Load¶

You can use the saved data with a simple line of code

from spy4cast.spy4cast import Preprocess

preprocessed = Preprocess.load('save_preprocess_', dir='saved')
preprocessed.plot(selected_year=1990, show_plot=True, save_fig=True, cmap='jet', dir='plots', name='plot.png')

from spy4cast.meteo import Clim

clim = Clim.load('save_clim_', dir='saved')
clim.plot(show_plot=True, save_fig=True, cmap='jet', dir='plots', name='plot.png')

Note

Load and Save work for Clim, Anom, Preprocess, MCA, Crossvalidation and Validation (every methodology the API supports)

Spy4Cast¶

The main methodology of spy4cast is Spy4Cast :-).

It requires a predictor dataset and a predictand dataset. Here is an example which you can download here

from spy4cast import Dataset, Region, Month
from spy4cast.spy4cast import Preprocess, MCA, Crossvalidation, Validation

predictor = Dataset('predictor.nc').open('predictor-var').slice(
    Region(-20, 30, -5, 40, Month.DEC, Month.MAR, 1870, 1990)
)

predictand = Dataset('predictand.nc').open('predictand-var').slice(
    Region(-50, -10, -40, 40, Month.JUN, Month.AUG, 1871, 1991)
)

Preprocess¶

We now preprocess everything. nm and alpha are required parameters

nm = 3
alpha = 0.1

predictor_preprocessed = Preprocess(predictor, order=5, period=11)  # If we supply `order` and `period` parameters, it applies a filter
predictand_preprocessed = Preprocess(predictand)

MCA¶

Apply MCA

mca = MCA(dsy=predictor_preprocessed, dsz=predictand_preprocessed, nm=nm, alpha=alpha)

Crossvalidation¶

Apply Crossvalidation

cross = Crossvalidation(dsy=predictor_preprocessed, dsz=predictand_preprocessed, nm=nm, alpha=alpha)

Validation¶

Apply Validation: needs a training period to compute the training MCA which then applies through out the validting period

training_preprocessed_y = Preprocess(training_predictor)
training_preprocessed_z = Preprocess(training_predictand)
training_mca = MCA(training_preprocessed_y, training_preprocessed_z, nm=3, alpha=0.1)

validating_preprocessed_y = Preprocess(validating_predictor)
validating_preprocessed_z = Preprocess(validating_predictand)

validation = Validation(training_mca, validating_preprocessed_y, validating_preprocessed_z)

Visualization¶

Check out the plotting section.

Plot¶

You can learn all about plotting in the Plotting section.

To plot the results of a methodology you can use the built in plot function. Its purpose is to be fast and to serve you as a debugging tool. For final results we reccommend you to create your own plotting functions.

Spy4Cast¶

Each spy4cast methodology has its own plotting functions: Spy4Cast.

Clim¶

Clim performs the climatology for the given region

from spy4cast import Dataset, Region, Month
from spy4cast.meteo import Clim

DIR = "data/"
NAME = "dataset.nc"
VAR = "sst"  # Variable to use in the dataset. For example `sst`
ds = Dataset(NAME, dir=DIR).open(VAR).slice(
    Region(-90, 90, -180, 180, Month.JAN, Month.MAR, 1870, 1995)
)
clim = Clim(ds, 'map')  # You can plot a time series with Clim(ds, 'ts')
clim.plot(show_plot=True, save_fig=True, cmap='jet', dir='plots', name='plot.png')

You can slice a dataset with only a Month and a year (Region(-90, 90, -180, 180, Month.JAN, Month.JAN, 1900, 1900)) and plot the clmatollogy of this dataset if you want to plot a certain month and year.

Anom¶

Anom performs the anomaly for the given region

from spy4cast import Dataset, Region, Month
from spy4cast.meteo import Anom

DIR = "data/"
NAME = "dataset.nc"
VAR = "sst"  # Variable to use in the dataset. For example `sst`
ds = Dataset(NAME, dir=DIR).open(VAR).slice(
    Region(-90, 90, -180, 180, Month.JAN, Month.MAR, 1870, 1995)
)
anom = Anom(ds, 'map')  # You can plot a time series with Clim(ds, 'ts')
# A year is needed because Anom produces lots of maps (if you use 'ts', the year parameter becomes invalid)
anom.plot(show_plot=True, save_fig=True, year=1990, cmap='jet', dir='plots', name='plot.png')