API

Core

These functions make up the core of the TAMS algorithm and are available at the top level (tams):

identify(ctt, *[, ctt_threshold, ...])	Identify clouds in 2-D (lat/lon) or 3-D (lat/lon + time) cloud-top temperature data ctt.
track(contours_sets, times, *[, ...])	Assign group IDs to the CEs identified at each time, returning a single CE frame.
classify(cs)	Classify the CE groups into MCS classes (categorical column 'mcs_class' in the result).

The helper function tams.run() combines the above plus additional processing, including computing stats on gridded data within the identified cloud element regions.

run(ds, *[, ctt_threshold, ...])

Run all TAMS steps, including precip assignment.

Lower level functions used in the above include:

contour(x, value, *[, unstructured, ...])	Contour x at value, producing a dataframe of contour lines.
data_in_contours(data, contours, *[, agg, ...])	Compute statistics on data within the shapes of contours.
eccentricity(p)	Compute the (first) eccentricity of the least-squares best-fit ellipse to the coordinates of the polygon's exterior.
overlap(a, b, *[, norm])	For each contour in a, determine those in b that overlap and by how much.
project(df, *[, u, dt])	Project the coordinates by u * dt meters in the x direction.

Ellipse fitting

Used by tams.eccentricity().

fit_ellipse(p)	Fit ellipse to the exterior coordinates of the polygon.
Ellipse(center, width, height, angle)	Ellipse fit parameters, e.g. returned by fit_ellipse().

Ellipse fit parameters:

Ellipse.center	Center (x, y) coordinates.
Ellipse.width	Diameter in the x-direction before rotation.
Ellipse.height	Diameter in the y-direction before rotation.
Ellipse.angle	Rotation angle (degrees) from x-axis to the width axis.

Ellipse properties/methods:

Ellipse.a	Semi-major axis length.
Ellipse.b	Semi-minor axis length.
Ellipse.c	The linear eccentricity (distance from center to focus).
Ellipse.e	Alias for eccentricity.
Ellipse.eccentricity	The (first) eccentricity.
Ellipse.to_blob()	Convert to Blob object, which provides further conversion methods.

Deprecated

calc_ellipse_eccen(p)

Calculate the (first) eccentricity of the least-squares best-fit ellipse to the coordinates of the polygon's exterior.

Data

tams.data

Loaders for various data sets.

fetch_example(key, *[, progress])	Retrieve an example data file using pooch and gdown.
open_example(key, *[, progress])	Open an example dataset with xarray.
load_example(key, *[, progress])	Load an example dataset into memory with xarray.
tb_from_ir(r, ch)	Compute brightness temperature from IR satellite radiances (r) in channel ch of the EUMETSAT MSG SEVIRI instrument.
get_mergir(time_or_range, *[, version, parallel])	Stream GPM MERGIR brightness temperature from NASA Earthdata.
get_imerg(time_or_range, *[, version, run, ...])	Stream GPM IMERG L3 precipitation from NASA Earthdata.

Example datasets

These can be accessed with tams.data.open_example() or tams.data.load_example().

Key	Description	Relevant example notebooks
msg-rad	Satellite infrared radiance data. This comes from the EUMETSAT MSG SEVIRI instrument, specifically the 10.8 μm channel (ch9). This dataset contains 6 time steps of 2-hourly data (every 2 hours): 2006-09-01 00–10
msg-tb	As in msg-rad but with tams.data.tb_from_ir() applied to convert radiance to brightness temperature (K).	Sample satellite data, Identify
imerg	GPM IMERG precipitation data. This is left-labeled half-hourly precipitation rate (mm/hr) fetched using tams.data.get_imerg() for the same period as the MSG data (2006-09-01 00:00–11:30; extended so that we have data for the full last two-hour period).	Sample satellite data
mpas-regridded	MPAS-A model output (regridded). This is a spatial and variable subset of native MPAS output, Furthermore, it has been regridded to a regular lat/lon grid (0.25°) from the original 15-km mesh. After regridding, it was spatially subsetted so that lat ranges from -5 to 40°N and lon from 85 to 170°E. This domain relates to the PRECIP field campaign. It has tb (estimated brightness temperature) and pr (precipitation rate, derived by summing the MPAS accumulated grid-scale and convective precip variables rainnc and rainc and differentiating). tb was estimated using the (black-body) Stefan–Boltzmann law: \[E = \sigma T^4 \implies T = (E / \sigma)^{1/4}\] where \(E\) is the OLR (outgoing longwave radiation, olrtoa in MPAS output) in W m-2 and \(\sigma\) is the Stefan–Boltzmann constant. This dataset contains 127 time steps of hourly data: 2006-09-08 12 – 2006-09-13 18.	tams.run(), Tracking options, MPAS unstructured grid data
mpas-native	MPAS-A native (unstructured grid) model output. This is a spatial and variable subset of native 15-km global mesh MPAS output. It has been spatially subsetted so that lat ranges from -5 to 20°N and lon from 85 to 170°E, similar to the example regridded MPAS dataset (mpas-regridded), except for a smaller lat upper bound. Like the regridded MPAS dataset, it has hourly tb (estimated brightness temperature) and precip (precipitation rate) for the period 2006-09-08 12 – 2006-09-13 18. Like the regridded MPAS dataset (mpas-regridded), tb was estimated using the (black-body) Stefan–Boltzmann law: \[E = \sigma T^4 \implies T = (E / \sigma)^{1/4}\] where \(E\) is the OLR (outgoing longwave radiation, olrtoa in MPAS output) in W m-2 and \(\sigma\) is the Stefan–Boltzmann constant.	MPAS unstructured grid data
mosa-test-1, …, mosa-test-4	Small idealized/test datasets from the MOSA paper [U2].

External data sources

Function	Description	Relevant example notebooks
tams.data.get_mergir()	GPM MERGIR brightness temperature from NASA.	Stream input data
tams.data.get_imerg()	GPM IMERG precipitation data from NASA.	Stream input data

Idealized

tams.idealized

Create and evolve systems of ellipsoidal blobs for demonstrating and testing TAMS.

See the example notebook for some demonstrations.

Blob([center, width, height, angle, depth, ...])	An elliptical blob that can be used to represent a cloud element (or part of one, if blobs are overlapping).
Field([blobs, lat, lon, ctt_background])	A field of blobs.
Sim([field, dt])	Simulate a field of blobs.

Blob properties:

Blob.ring	The ellipse perimeter as a shapely.LinearRing.
Blob.polygon	The ellipse as a shapely.Polygon.

Transform blobs:

Blob.set_tendency(**kwargs)	Set in place the tendency of one or more of the ellipse parameters in per hour units.
Blob.get_tendency([key, copy])	Get the current tendency of one or all (default) of the ellipse parameters.
Blob.evolve(hours, /)	Evolve the blob in place by the given number of hours.
Blob.merge(other)	Merge with another blob, creating a new blob with area-weighted-average characteristics.
Blob.split([n])	Split the blob into n smaller blobs that line up along the minor axis.
Blob.copy()	Return a copy of the blob.
Blob.to_geopandas(*[, crs])	Convert the blob to a GeoPandas GeoSeries, using the polygon.
Blob.to_patch(**kwargs)	Convert the blob to a Matplotlib Ellipse patch.

Compute the blob’s impact on the field:

Blob.well(x, y)

Parabolic well function.

Transform a collection of blobs:

Field.evolve(hours, /)	Evolve the field in place by the given number of hours.
Field.to_xarray(*[, ctt_threshold, additive])	Convert the field to an xarray DataArray.
Field.to_geopandas(*[, crs])	Convert the field to a GeoPandas GeoDataFrame.
Field.copy()	Return a copy of the field.

Simulate a collection of blobs:

Sim.advance(steps, /)	Advance the simulation by the given number of time steps.
Sim.to_xarray(*[, start])	Convert the history and current field to an xarray DataArray.

Utilities

Currently this is available at the top level (tams), but it may be separate in the future.

plot_tracked(cs, *[, alpha, background, ...])

Plot CEs at a range of times (colors) with CE group ID (MCS ID) identified.

Options

Like the core routines, options management is available at the top level (tams).

set_options(**kwargs)	Globally or temporarily (context manager) set options.
get_options()	Get current options (a copy, edits have no effect).