7.1.1. tobac.analysis.analysis¶

Provide tools to analyse and visualize the tracked objects.

This module provides a set of routines that enables performing analyses and deriving statistics for individual clouds, such as the time series of integrated properties and vertical profiles. It also provides routines to calculate summary statistics of the entire populatin of tracked clouds in the cloud field like histograms of cloud areas/volumes or cloud mass and a detailed cell lifetime analysis. These analysis routines are all built in a modular manner. Thus, users can reuse the most basic methods for interacting with the data structure of the package in their own analysis procedures in Python. This includes functions perfomring simple tasks like looping over all identified objects or cloud trajectories and masking arrays for the analysis of individual cloud objects. Plotting routines include both visualizations for individual convective cells and their properties.

Functions

area_histogram(features, mask[, bin_edges, …])

Parameters:	features

calculate_area(features, mask[, method_area])

Parameters:	features

calculate_distance(feature_1, feature_2[, …]) Computes distance between two features.

calculate_nearestneighbordistance(features)

Parameters:	features

calculate_overlap(track_1, track_2[, …])

Parameters:	track_1, track_2

calculate_velocity(track[, method_distance])

Parameters:	track

calculate_velocity_individual(feature_old, …)

Parameters:	feature_old

cell_statistics(input_cubes, track, mask, …)

Parameters:	input_cubes (iris.cube.Cube)

cell_statistics_all(input_cubes, track, …)

Parameters:	input_cubes (iris.cube.Cube)

haversine(lat1, lon1, lat2, lon2) Computes the Haversine distance in kilometers.

histogram_cellwise(Track[, variable, …])

Parameters:	Track

histogram_featurewise(Track[, variable, …])

Parameters:	Track

lifetime_histogram(Track[, bin_edges, …])

Parameters:	Track

nearestneighbordistance_histogram(features)

Parameters:	features

velocity_histogram(track[, bin_edges, …])

Parameters:	track

tobac.analysis.analysis.area_histogram(features, mask, bin_edges=array([ 0, 500, 1000, 1500, 2000, 2500, 3000, 3500, 4000, 4500, 5000, 5500, 6000, 6500, 7000, 7500, 8000, 8500, 9000, 9500, 10000, 10500, 11000, 11500, 12000, 12500, 13000, 13500, 14000, 14500, 15000, 15500, 16000, 16500, 17000, 17500, 18000, 18500, 19000, 19500, 20000, 20500, 21000, 21500, 22000, 22500, 23000, 23500, 24000, 24500, 25000, 25500, 26000, 26500, 27000, 27500, 28000, 28500, 29000, 29500]), density=False, method_area=None, return_values=False, representative_area=False)¶

Parameters:

features
mask (iris.cube.Cube) – Cube containing mask (int id for tracked volumes 0 everywhere else).
bin_edges (ndarray, optional) – Default is np.arange(0, 30000, 500).
density (bool, optional) – Default is False.
representive_area (bool, optional) – Default is False.

Returns:

hist
bin_edges (ndarray)
bin_centers
areas

Notes

short summary, types and descriptions

tobac.analysis.analysis.calculate_area(features, mask, method_area=None)¶

Parameters:

features
mask (iris.cube.Cube) – Cube containing mask (int for tracked volumes 0 everywhere else).
method_area ({None, ‘xy’, ‘latlon’}, optional) – Default is None.

Returns:

hist
bin_edges (ndarray)
bin_centers
areas

Raises:

ValueError – If neither latitude/longitude nor projection_x_coordinate/projection_y_coordinate are present in mask_coords.

If latitude/longitude coordinates are 2D.

If latitude/longitude shapes are not supported.

If method is undefined, e.i. method is neither None, ‘xy’ nor ‘latlon’.

Notes

needs short summary, types and descriptions

tobac.analysis.analysis.calculate_distance(feature_1, feature_2, method_distance=None)¶

Computes distance between two features.

It is based on either lat/lon coordinates or x/y coordinates.

Parameters:	feature_1, feature_2 (array of latitude, longitute) – First and second feature or points as array in degrees. method_distance ({None, ‘xy’, ‘latlon’}, optional) – Default is None.
Returns:	distance – Between the two features in meters.
Return type:	float

Notes

check sense of types and descriptions

tobac.analysis.analysis.calculate_nearestneighbordistance(features, method_distance=None)¶

Parameters:	features method_distance ({None, ‘xy’, ‘latlon’}, optional) – Default is None.
Returns:
Return type:	features

Notes

short summary, types and descriptions

tobac.analysis.analysis.calculate_overlap(track_1, track_2, min_sum_inv_distance=None, min_mean_inv_distance=None)¶

Parameters:	track_1, track_2 min_sum_inv_distance (optional) – Default is None. min_mean_inv_distance (optional) – Default is None.
Returns:	overlap
Return type:	pandas.DataFrame

Notes

short summary, types and descriptions

tobac.analysis.analysis.calculate_velocity(track, method_distance=None)¶

Parameters:	track method_distance ({None, ‘xy’, ‘latlon’}, optional) – Default is None.
Returns:
Return type:	track

Notes

needs short summary, description and type of track

tobac.analysis.analysis.calculate_velocity_individual(feature_old, feature_new, method_distance=None)¶

Parameters:	feature_old feature_new method_distance ({None, ‘xy’, ‘latlon’}, optional) – Default is None.

Notes

feature_old and feature_new need types and descriptions needs a short summary

tobac.analysis.analysis.cell_statistics(input_cubes, track, mask, aggregators, cell, output_path='./', output_name='Profiles', width=10000, z_coord='model_level_number', dimensions=['x', 'y'], **kwargs)¶

Parameters:	input_cubes (iris.cube.Cube) track (dask.dataframe.DataFrame) mask (iris.cube.Cube) – Cube containing mask (int id for tracked volumes 0 everywhere else). aggregators cell (int) – Integer id of cell to create masked cube for output. output_path (str, optional) – Default is ‘./’. output_name (str, optional) – Default is ‘Profiles’. width (int, optional) – Default is 10000. z_coord (str, optional) – Name of the vertical coordinate in the cube. Default is ‘model_level_number’. dimensions (list of str, optional) – Default is [‘x’, ‘y’]. **kwargs
Returns:
Return type:	None

Notes

unsure about anything needs a short summary

tobac.analysis.analysis.cell_statistics_all(input_cubes, track, mask, aggregators, output_path='./', cell_selection=None, output_name='Profiles', width=10000, z_coord='model_level_number', dimensions=['x', 'y'], **kwargs)¶

Parameters:	input_cubes (iris.cube.Cube) track (dask.dataframe.DataFrame) mask (iris.cube.Cube) – Cube containing mask (int id for tracked volumes 0 everywhere else). aggregators output_path (str, optional) – Default is ‘./’. cell_selection (optional) – Default is None. output_name (str, optional) – Default is ‘Profiles’. width (int, optional) – Default is 10000. z_coord (str, optional) – Name of the vertical coordinate in the cube. Default is ‘model_level_number’. dimensions (list of str, optional) – Default is [‘x’, ‘y’]. **kwargs
Returns:
Return type:	None

Notes

unsure about anything needs a short summary

tobac.analysis.analysis.haversine(lat1, lon1, lat2, lon2)¶

Computes the Haversine distance in kilometers.

Calculates the Haversine distance between two points (based on implementation CIS https://github.com/cedadev/cis).

Parameters:	lat1, lon1 (array of latitude, longitude) – First point or points as array in degrees. lat2, lon2 (array of latitude, longitude) – Second point or points as array in degrees.
Returns:	*arclen RADIUS_EARTH** – Distance between the two points in kilometers.
Return type:	float

Notes

check types

RADIUS_EARTH = 6378.0

tobac.analysis.analysis.histogram_cellwise(Track, variable=None, bin_edges=None, quantity='max', density=False)¶

Parameters:

Track
variable (optional) – Default is None.
bin_edges (ndarray, optional) – Default is None.
quantity ({‘max’, ‘min’, ‘mean’}, optional) – Default is ‘max’.
density (bool, optional) – Default is False.

Returns:

hist
bin_edges (ndarray)
bin_centers

Raises:

ValueError – If quantity is not ‘max’, ‘min’ or ‘mean’.

Notes

short summaray, types and descriptions

tobac.analysis.analysis.histogram_featurewise(Track, variable=None, bin_edges=None, density=False)¶

Parameters:

Track
variable (optional) – Default is None.
bin_edges (ndarray, optional) – Default is None.
density (bool, optional) – Default is False.

Returns:

hist
bin_edges (ndarray)
bin_centers

Notes

short summaray, types and descriptions

tobac.analysis.analysis.lifetime_histogram(Track, bin_edges=array([ 0, 20, 40, 60, 80, 100, 120, 140, 160, 180]), density=False, return_values=False)¶

Parameters:

Track
bin_edged (ndarray, optional) – Default is np.arange(0, 200, 20).
density (bool, optional) – Default is False.
return_values (bool, optional) – Default is False.

Returns:

hist
bin_edges (ndarray)
bin_centers
minutes (float)

Notes

unsure about anything needs short summary

tobac.analysis.analysis.nearestneighbordistance_histogram(features, bin_edges=array([ 0, 500, 1000, 1500, 2000, 2500, 3000, 3500, 4000, 4500, 5000, 5500, 6000, 6500, 7000, 7500, 8000, 8500, 9000, 9500, 10000, 10500, 11000, 11500, 12000, 12500, 13000, 13500, 14000, 14500, 15000, 15500, 16000, 16500, 17000, 17500, 18000, 18500, 19000, 19500, 20000, 20500, 21000, 21500, 22000, 22500, 23000, 23500, 24000, 24500, 25000, 25500, 26000, 26500, 27000, 27500, 28000, 28500, 29000, 29500]), density=False, method_distance=None, return_values=False)¶

Parameters:

features
bin_edges (ndarray, optional) – Default is np.arange(0, 30000, 500).
density (bool, optional) – Default is False.
method_distance ({None, ‘xy’, ‘latlon’}, optional) – Default is None.

Returns:

hist
bin_edges (ndarray)
distances

Notes

short summary, types and descriptions

tobac.analysis.analysis.velocity_histogram(track, bin_edges=array([ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29]), density=False, method_distance=None, return_values=False)¶

Parameters:

track
bin_edges (ndarray, optional) – Default is np.arange(0, 30, 1).
density (bool, optional) – Default is False.
methods_distance ({None, ‘xy’, ‘latlon’}, optional) – Default is None.
return_values (bool, optional) – Default is False.

Returns:

hist
bin_edges (ndarray)
velocities

Notes

short summary, types and descriptions