tams.run()#

tams.run() is a convenience function that does

  1. tams.identify()

  2. tams.track()

  3. tams.classify()

  4. aggregation and statistics

Using a selection of the example post-processed MPAS data, we investigate its outputs.

import xarray as xr

import tams

xr.set_options(display_expand_data=False)

Hide code cell output

<xarray.core.options.set_options at 0x7b41715f9bd0>

tams.run() expects certain variable names.

ds = tams.load_example_mpas().rename({"tb": "ctt", "precip": "pr"}).isel(time=slice(1, 13))
ds
<xarray.Dataset> Size: 6MB
Dimensions:  (time: 12, lat: 180, lon: 341)
Coordinates:
  * time     (time) datetime64[ns] 96B 2006-09-08T13:00:00 ... 2006-09-09
  * lon      (lon) float64 3kB 85.0 85.25 85.5 85.75 ... 169.2 169.5 169.8 170.0
  * lat      (lat) float64 1kB -4.875 -4.625 -4.375 -4.125 ... 39.38 39.62 39.88
Data variables:
    ctt      (time, lat, lon) float32 3MB 266.8 266.9 267.0 ... 262.9 261.2
    pr       (time, lat, lon) float32 3MB ...

tams.run() produces three output datasets.

%%time

ce, mcs, mcs_summary = tams.run(ds, parallel=True)

Hide code cell output

Starting `identify` 2025-09-13 20:45:26
[Parallel(n_jobs=-2)]: Done   1 tasks      | elapsed:    0.5s
[Parallel(n_jobs=-2)]: Done   4 tasks      | elapsed:    0.8s
[Parallel(n_jobs=-2)]: Done   7 tasks      | elapsed:    1.0s
[Parallel(n_jobs=-2)]: Done  12 tasks      | elapsed:    1.5s
[Parallel(n_jobs=-2)]: Done  12 out of  12 | elapsed:    1.5s finished
Starting `track` 2025-09-13 20:45:27
Starting `classify` 2025-09-13 20:45:27
Starting statistics calculations 2025-09-13 20:45:28
Starting CE aggregation (into MCS time series) 2025-09-13 20:45:28
Starting gridded data aggregation 2025-09-13 20:45:28
[Parallel(n_jobs=-2)]: Done   1 tasks      | elapsed:    0.4s
[Parallel(n_jobs=-2)]: Done   4 tasks      | elapsed:    1.4s
[Parallel(n_jobs=-2)]: Done   7 tasks      | elapsed:    2.5s
Computing stats for MCS summary dataset 2025-09-13 20:45:32
Done 2025-09-13 20:45:32
CPU times: user 6.62 s, sys: 209 ms, total: 6.82 s
Wall time: 6.84 s
[Parallel(n_jobs=-2)]: Done  12 tasks      | elapsed:    4.3s
[Parallel(n_jobs=-2)]: Done  12 out of  12 | elapsed:    4.3s finished

CE dataset#

Identified cloud elements (CEs). Tracking has added mcs_id; classification has added mcs_class.

Each row corresponds to a CE–time that belongs to an MCS. A certain MCS at a given time may include multiple CEs.

ce
cs235 area_km2 area219_km2 cs219 time mcs_id mcs_class
0 POLYGON ((167.5 9.49188, 167.75 9.58423, 167.7... 25634.1184 11798.035271 MULTIPOLYGON (((167.5 9.61125, 167.53439 9.625... 2006-09-08 13:00:00 0 DSL
1 POLYGON ((152.5 8.79886, 152.61238 8.875, 154.... 79372.537834 48340.476814 MULTIPOLYGON (((152.75 10.37642, 153 10.44407,... 2006-09-08 13:00:00 1 DSL
2 POLYGON ((148.75 8.23715, 149 8.27821, 149.109... 14036.478097 7223.353767 MULTIPOLYGON (((148.75 8.34082, 148.99758 8.37... 2006-09-08 13:00:00 2 DSL
3 POLYGON ((147.25 7.01224, 147.75 7.01643, 148 ... 22263.09014 6159.967885 MULTIPOLYGON (((147.75 7.1996, 148 7.32651, 14... 2006-09-08 13:00:00 3 DSL
4 POLYGON ((138.25 15.00363, 138.5 15.05098, 138... 10596.159009 5433.912228 MULTIPOLYGON (((138.25 15.10322, 138.33471 15.... 2006-09-08 13:00:00 4 DSL
... ... ... ... ... ... ... ...
306 POLYGON ((101.75 17.48897, 103 17.52605, 103.2... 296457.481388 98134.338311 MULTIPOLYGON (((107.5 20.06175, 107.65073 20.1... 2006-09-09 00:00:00 98 DSL
307 POLYGON ((101.75 -1.71823, 102.25 -1.65082, 10... 732976.336208 429992.676965 MULTIPOLYGON (((108.25 3.023, 108.39196 3.125,... 2006-09-09 00:00:00 71 CCC
308 POLYGON ((94.75 0.87272, 94.78525 0.875, 95 0.... 1535138.591424 772410.489496 MULTIPOLYGON (((95.75 6.2973, 95.858 6.375, 95... 2006-09-09 00:00:00 71 CCC
309 POLYGON ((97 22.14142, 97.25 22.17086, 97.75 2... 780231.600791 309818.201344 MULTIPOLYGON (((98.25 22.91528, 98.28253 23.12... 2006-09-09 00:00:00 101 DSL
310 POLYGON ((86.25 19.75351, 86.5 19.77476, 86.75... 53903.194943 20853.307518 MULTIPOLYGON (((87.25 21.32294, 87.5 21.33814,... 2006-09-09 00:00:00 95 DSL

311 rows × 7 columns

ce.info()
<class 'geopandas.geodataframe.GeoDataFrame'>
RangeIndex: 311 entries, 0 to 310
Data columns (total 7 columns):
 #   Column       Non-Null Count  Dtype         
---  ------       --------------  -----         
 0   cs235        311 non-null    geometry      
 1   area_km2     311 non-null    Float64       
 2   area219_km2  311 non-null    Float64       
 3   cs219        311 non-null    geometry      
 4   time         311 non-null    datetime64[ns]
 5   mcs_id       311 non-null    Int64         
 6   mcs_class    311 non-null    category      
dtypes: Float64(2), Int64(1), category(1), datetime64[ns](1), geometry(2)
memory usage: 16.0 KB
ce.area_km2.describe()
count             311.0
mean      322513.334878
std       454722.354567
min        10377.283677
25%         45083.40339
50%       158404.664835
75%       415329.825091
max      3252490.158201
Name: area_km2, dtype: Float64

MCS dataset#

At each time, CEs with the same MCS ID are combined into one.

Some statistics of precip (pr) and cloud-top temperature (ctt) within the MCS areas are included.

Each row corresponds to an MCS–time.

mcs
time cs235 cs219 nce area_km2 area219_km2 mcs_id mcs_class mean_pr std_pr npixel mean_pr219 std_pr219 mean_ctt219 std_ctt219 npixel219
0 2006-09-08 13:00:00 MULTIPOLYGON (((167.5 9.49188, 167.75 9.58423,... MULTIPOLYGON (((167.5 9.61125, 167.53439 9.625... 1 25634.1184 11798.035271 0 DSL 2.645099 0.927722 36 3.28087 0.533223 209.896072 4.906273 18
1 2006-09-08 13:00:00 MULTIPOLYGON (((152.5 8.79886, 152.61238 8.875... MULTIPOLYGON (((152.75 10.37642, 153 10.44407,... 1 79372.537834 48340.476814 1 DSL 1.910169 1.426157 106 2.547689 1.304625 215.991379 16.687454 64
2 2006-09-08 13:00:00 MULTIPOLYGON (((148.75 8.23715, 149 8.27821, 1... MULTIPOLYGON (((148.75 8.34082, 148.99758 8.37... 1 14036.478097 7223.353767 2 DSL 2.254961 0.982726 19 2.883151 0.706086 213.163315 4.442413 11
3 2006-09-08 13:00:00 MULTIPOLYGON (((147.25 7.01224, 147.75 7.01643... MULTIPOLYGON (((147.75 7.1996, 148 7.32651, 14... 1 22263.09014 6159.967885 3 DSL 2.019073 0.856571 29 2.915771 0.337212 214.483337 2.475573 9
4 2006-09-08 13:00:00 MULTIPOLYGON (((138.25 15.00363, 138.5 15.0509... MULTIPOLYGON (((138.25 15.10322, 138.33471 15.... 1 10596.159009 5433.912228 4 DSL 1.95028 0.935729 15 2.571446 0.641791 211.823792 5.197964 8
... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ...
266 2006-09-09 00:00:00 MULTIPOLYGON (((126 16.04305, 126.25 16.10036,... MULTIPOLYGON (((127.75 19.60362, 127.75 19.603... 4 963155.281892 326920.015309 98 DSL 0.951342 1.145551 1243 1.412011 1.488934 214.811386 6.743108 440
267 2006-09-09 00:00:00 MULTIPOLYGON (((148.75 -2.21941, 149.5 -2.2141... MULTIPOLYGON (((150.5 -0.67942, 150.55409 -0.6... 1 157397.412137 40993.731489 100 DSL 0.900998 0.597975 205 1.25952 0.619944 217.582062 4.004134 55
268 2006-09-09 00:00:00 MULTIPOLYGON (((97 22.14142, 97.25 22.17086, 9... MULTIPOLYGON (((98.25 22.91528, 98.28253 23.12... 1 780231.600791 309818.201344 101 DSL 1.046286 2.042402 1002 1.905522 2.855528 216.48819 13.512681 393
269 2006-09-09 00:00:00 MULTIPOLYGON (((168.75 19.50717, 170 19.75475,... MULTIPOLYGON (((169 22.58414, 169.03442 22.625... 1 724340.022743 12713.449719 102 DSL 1.05563 0.930567 931 1.742241 1.036302 218.198257 3.076819 24
270 2006-09-09 00:00:00 MULTIPOLYGON (((129.5 30.22046, 130 30.22383, ... MULTIPOLYGON (((130 30.3112, 130.12126 30.375,... 1 59910.587417 22585.544931 103 DSL 1.321026 0.87163 80 1.65364 0.771776 216.026505 7.512138 33

271 rows × 16 columns

mcs.info()
<class 'geopandas.geodataframe.GeoDataFrame'>
RangeIndex: 271 entries, 0 to 270
Data columns (total 16 columns):
 #   Column       Non-Null Count  Dtype         
---  ------       --------------  -----         
 0   time         271 non-null    datetime64[ns]
 1   cs235        271 non-null    geometry      
 2   cs219        271 non-null    geometry      
 3   nce          271 non-null    Int64         
 4   area_km2     271 non-null    Float64       
 5   area219_km2  271 non-null    Float64       
 6   mcs_id       271 non-null    Int64         
 7   mcs_class    271 non-null    category      
 8   mean_pr      271 non-null    Float64       
 9   std_pr       271 non-null    Float64       
 10  npixel       271 non-null    Int64         
 11  mean_pr219   271 non-null    Float64       
 12  std_pr219    271 non-null    Float64       
 13  mean_ctt219  271 non-null    Float64       
 14  std_ctt219   271 non-null    Float64       
 15  npixel219    271 non-null    Int64         
dtypes: Float64(8), Int64(4), category(1), datetime64[ns](1), geometry(2)
memory usage: 35.4 KB

MCS summary dataset#

No more shapes (just first and last centroid points).

Each row corresponds to an MCS, including some statistics for the track such as the MCS’s duration and initial and final coordinates.

mcs_summary
first_time last_time duration mcs_id mcs_class mean_mean_pr mean_mean_pr219 mean_mean_ctt219 mean_std_ctt219 mean_area_km2 mean_area219_km2 mean_nce first_centroid last_centroid distance_km
0 2006-09-08 13:00:00 2006-09-08 13:00:00 0 days 01:00:00 0 DSL 2.645099 3.28087 209.896072 4.906273 25634.1184 11798.035271 1.0 POINT (166.99291 10.21816) POINT (166.99291 10.21816) 0.0
1 2006-09-08 13:00:00 2006-09-08 13:00:00 0 days 01:00:00 1 DSL 1.910169 2.547689 215.991379 16.687454 79372.537834 48340.476814 1.0 POINT (152.90791 10.97758) POINT (152.90791 10.97758) 0.0
2 2006-09-08 13:00:00 2006-09-08 13:00:00 0 days 01:00:00 2 DSL 2.254961 2.883151 213.163315 4.442413 14036.478097 7223.353767 1.0 POINT (148.77232 8.90816) POINT (148.77232 8.90816) 0.0
3 2006-09-08 13:00:00 2006-09-08 13:00:00 0 days 01:00:00 3 DSL 2.019073 2.915771 214.483337 2.475573 22263.09014 6159.967885 1.0 POINT (147.51589 7.72076) POINT (147.51589 7.72076) 0.0
4 2006-09-08 13:00:00 2006-09-08 13:00:00 0 days 01:00:00 4 DSL 1.95028 2.571446 211.823792 5.197964 10596.159009 5433.912228 1.0 POINT (137.91402 15.61447) POINT (137.91402 15.61447) 0.0
... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ...
99 2006-09-08 22:00:00 2006-09-08 22:00:00 0 days 01:00:00 99 DSL 1.65246 1.845998 217.693146 5.018254 27287.757427 13371.649506 1.0 POINT (104.65093 -0.2743) POINT (104.65093 -0.2743) 0.0
100 2006-09-08 23:00:00 2006-09-09 00:00:00 0 days 02:00:00 100 DSL 0.933822 1.233324 216.869774 2.780729 131313.619017 24776.843726 1.0 POINT (149.0416 -0.65489) POINT (148.86278 -0.27059) 47.185759
101 2006-09-08 23:00:00 2006-09-09 00:00:00 0 days 02:00:00 101 DSL 1.131009 2.072433 215.648209 13.630206 715452.49923 304477.598491 1.0 POINT (91.68003 25.6258) POINT (92.35389 25.77116) 76.739478
102 2006-09-09 00:00:00 2006-09-09 00:00:00 0 days 01:00:00 102 DSL 1.05563 1.742241 218.198257 3.076819 724340.022743 12713.449719 1.0 POINT (165.95451 29.77248) POINT (165.95451 29.77248) 0.0
103 2006-09-09 00:00:00 2006-09-09 00:00:00 0 days 01:00:00 103 DSL 1.321026 1.65364 216.026505 7.512138 59910.587417 22585.544931 1.0 POINT (129.22112 31.61942) POINT (129.22112 31.61942) 0.0

104 rows × 15 columns

mcs_summary.info()
<class 'geopandas.geodataframe.GeoDataFrame'>
RangeIndex: 104 entries, 0 to 103
Data columns (total 15 columns):
 #   Column            Non-Null Count  Dtype          
---  ------            --------------  -----          
 0   first_time        104 non-null    datetime64[ns] 
 1   last_time         104 non-null    datetime64[ns] 
 2   duration          104 non-null    timedelta64[ns]
 3   mcs_id            104 non-null    Int64          
 4   mcs_class         104 non-null    category       
 5   mean_mean_pr      104 non-null    Float64        
 6   mean_mean_pr219   104 non-null    Float64        
 7   mean_mean_ctt219  104 non-null    Float64        
 8   mean_std_ctt219   104 non-null    Float64        
 9   mean_area_km2     104 non-null    Float64        
 10  mean_area219_km2  104 non-null    Float64        
 11  mean_nce          104 non-null    Float64        
 12  first_centroid    104 non-null    geometry       
 13  last_centroid     104 non-null    geometry       
 14  distance_km       104 non-null    Float64        
dtypes: Float64(8), Int64(1), category(1), datetime64[ns](2), geometry(2), timedelta64[ns](1)
memory usage: 12.6 KB
mcs_summary.describe()
first_time last_time duration mcs_id mean_mean_pr mean_mean_pr219 mean_mean_ctt219 mean_std_ctt219 mean_area_km2 mean_area219_km2 mean_nce distance_km
count 104 104 104 104.0 104.0 104.0 104.0 104.0 104.0 104.0 104.0 104.0
mean 2006-09-08 16:23:04.615384576 2006-09-08 17:59:25.384615424 0 days 02:36:20.769230769 51.5 1.156704 1.61739 213.8578 7.218748 208890.559483 83853.57485 1.066083 58.185853
min 2006-09-08 13:00:00 2006-09-08 13:00:00 0 days 01:00:00 0.0 0.187491 0.456384 205.555122 0.343413 10596.159009 4474.283814 1.0 0.0
25% 2006-09-08 14:00:00 2006-09-08 15:00:00 0 days 01:00:00 25.75 0.770805 1.092501 211.329475 4.331841 28062.533802 9114.303342 1.0 0.0
50% 2006-09-08 15:30:00 2006-09-08 17:00:00 0 days 01:00:00 51.5 1.059372 1.393241 214.508239 6.731265 65245.319034 18828.285517 1.0 0.0
75% 2006-09-08 18:00:00 2006-09-08 21:00:00 0 days 03:00:00 77.25 1.45971 1.95973 216.562508 9.324257 207862.252969 76796.45252 1.0 53.377108
max 2006-09-09 00:00:00 2006-09-09 00:00:00 0 days 10:00:00 103.0 3.069273 6.575438 222.817734 20.814117 2000734.41701 812164.938688 2.666667 750.167907
std NaN NaN 0 days 02:30:49.401384730 30.166206 0.547035 0.857315 3.514747 4.020769 351372.669445 150007.990804 0.226198 117.328995