First steps¶

Getting data¶

There are two ways of loading data in CliMetLab, using data sources or datasets.

Data sources¶

Data sources implement various methods to access and decode data. When data are downloaded from a remote site, they are cached on the local computer.

CliMetLab will infer the type of data by probing the downloaded file. If the file contains gridded data, such as meteorological fields, they will be accessible as an Xarray dataset, using the to_xarray() method. If the file contains point data, such as observation, they will be accessible as an as Pandas frame, using the to_pandas() method. Other data may only be available as NumPy arrays using the to_numpy() method.

The following example downloads a .csv file from NOAA’s International Best Track Archive for Climate Stewardship (IBTrACS) using the url data source. The file is downloaded into the local cache. It is then converted as a Pandas frame. The rows corresponding to the severe tropical cyclone Uma are extracted and plotted (more on plotting below).

import climetlab as cml

data = cml.load_source(
    "url",
    (
        "https://www.ncei.noaa.gov/data/international-best-track-archive-for-climate-stewardship-ibtracs"
        "/v04r00/access/csv/ibtracs.SP.list.v04r00.csv"
    ),
)

pd = data.to_pandas()
uma = pd[pd.NAME == "UMA:VELI"]
cml.plot_map(uma, style="cyclone-track")

Name	Parameter	Description
`"file"`	A path to a local file name.	TODO. Read more. (Notebook).
`"url"`	A URL to a remote file.	TODO. Read more. (Notebook).
`"cds"`	A request to the CDS API.	A request to retrieve data from the Copernicus Climate Data Store (CDS). Requires an account. Read more. (Notebook).
`"mars"`	TODO	A request to retrieve data from ECMWF’s meteorological archive (MARS), using the ECMWF web API. Requires an account. Read more. (Notebook).

Datasets¶

Datasets are a higher-level concept compared to data sources.

Todo

metadata, hidden access to sources, control plotting, control conversion to pandas

The following Python code:

import climetlab as cml

data = cml.load_dataset("hurricane-database", bassin="atlantic")
print(data.home_page)

will print:

https://www.aoml.noaa.gov/hrd/hurdat/Data_Storm.html

then,

irma = data.to_pandas(name="irma", year=2017)
cml.plot_map(irma)

will plot:

Compare that with the data source example.

Simple plotting¶

CliMetLab will try to select the best way to plot data.

cml.plot_map(data)

Below are the parameters you can pass to the plot function:

Name	Value	Default	Description
title	str or bool	`False`	The title of the plot. Use `True` for automatic.
projection	str	`None`	The name of a map projection. Use `None` for automatic. See below for possible values.
style	str	`None`	The name of a plotting to apply. Use `None` for default. See below for possible values.
foreground	str	`None`	TODO. See below for possible values.
background	str	`None`	TODO. See below for possible values.
path	str	`None`	Save the plot in a file instead of displaying it. The file type is inferred from the path extension (`.png`, `.pdf`, `.svg`, …)

You can find out what are the possible values for projection, style, foreground and background parameters using the code below:

import climetlab.plotting

# List of possible projections
for p in climetlab.plotting.projections():
    print(p)

# List of possible styles
for p in climetlab.plotting.styles():
    print(p)

# List of possible backgrounds/foregrounds
for p in climetlab.plotting.layers():
    print(p)

To get more information about a given projection, in a Jupyter Notebook:

from climetlab.plotting import projection

projection("global")

will output:

Name:	global
Collection:	projections
Path:	/opt/venv/lib/python3.7/site-packages/climetlab/data/projections/global.yaml
Definition:	magics: mmap: subpage_lower_left_latitude: -90.0 subpage_lower_left_longitude: -180.0 subpage_map_projection: cylindrical subpage_upper_right_latitude: 90.0 subpage_upper_right_longitude: 180.0

Advanced plotting¶

There are two options to plot several datasets on the same map. If you do not need to specify data specific parameters (e.g. style), you can call cml.plot_map() with a list of data objects.

cml.plot_map((data1, data2), foreground=False)

or, if you want to specify a per-data custom style, you can use cml.new_map():

p = cml.new_plot(projection="global")
p.plot_map(data1, style="style1")
p.plot_map(data2, style="style2")
p.show()