There are two ways of loading data in CliMetLab, using data
sources <data-sources>
or datasets <datasets>
.
Data sources implement various methods to access and decode data. When data are downloaded from a remote site, they are cached
<caching>
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).
datasource-example.py
Name | Parameter | Description |
---|---|---|
"file" |
A path to a local file name. | TODO. Read more <data-sources-file> . (Notebook). |
"url" |
A URL to a remote file. | TODO. Read more <data-sources-url> . (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 <data-sources-cds> . (Notebook). |
"mars" |
TODO | A request to retrieve data from ECMWF's meteorological archive (MARS), using the ECMWF web API. Requires an account. Read more <data-sources-mars> . (Notebook). |
Datasets are a higher-level concept compared to data sources.
metadata, hidden access to sources, control plotting, control conversion to pandas
The following Python code:
dataset-example.py
will print:
https://www.aoml.noaa.gov/hrd/hurdat/Data_Storm.html
then,
dataset-example.py
will plot:
Compare that with the data source example.
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:
print-magics-objects.py
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 |
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()