colindex2 2.11.3

depression detection/tracking schemes

colindex2

A Python package for detecting and tracking atmospheric disturbances. It is primarily designed to capture upper-tropospheric systems, such as cutoff lows, and to define their intensity indices.

• Snapshot-based: Capable of extracting features directly from snapshots.

• Early-stage tracking: Seamlessly trace disturbances from their initial phase along with continuous feature parameter transitions.

• Global and scale-selective: Extract disturbances within any size range, across all latitudes and vertical levels.

• Mesh-agnostic: Independent of data mesh structures (since v2.11).

• GPU acceleration: High-speed computation powered by GPUs (experimental).

Reference

• Kasuga, S., M. Honda, J. Ukita, S. Yaname, H. Kawase, and A. Yamazaki, 2021: Seamless detection of cutoff lows and preexisting troughs. Monthly Weather Review, 149, 3119–3134, https://doi.org/10.1175/MWR-D-20-0255.1, Supplimental Material

• Kasuga, S., and M. Honda, 2025: Climatology of Cutoff Lows Approaching Japan. SOLA, 21, 329-333, https://doi.org/10.2151/sola.2025-049, Supplimental Material

Install

pip install colindex2

Dependecies are...

numpy pandas polars pytorch scipy xarray netCDF4 h5netcdf matplotlib cartopy threadpoolctl

Tutorial

Try quick tutorial

How to execute

Two different ways are available using (1) python functions and (2) command lines

(1) Python functions -> documents

(2) Shell commands

Add -h to see documets.

• 1. Generate data_settings.py

gen_data_settings

• 2. Edit data_settings.py
• 3. Run detection

detect z.nc

• 4. Run tracking

track

or, you can do doth if multiple timesteps are included in input, as follows:

detect z.nc -track

• Find and make each tracking data

find_track ./d01 L 300 a

[!NOTE] the tracking data will be automatically saved in ./d01/T/ directory by default from v2.11.2, whose format is netcdf. If you use find_track command (or Finder() instance in python), the output will be csv format.

Directory structure of outputs

current_dir/
|
└── d01/  # default name
    |
    ├── AS/yyyymm  # 2D averaged slope function
    |       └── AS-{ty}-{yyyymmddhhTT}-{llll}.nc (or .grd)
    |
    ├── V/yyyymm   # point values after detection, will be used for tracking
    |       └── V-{ty}-{yyyymmddhhTT}-{llll}.csv
    |
    ├── Vt/yyyymm  # intermediate data (you can remove after all processes finished)
    |       └── V-{ty}-{yyyymmddhhTT}-{llll}.csv
    |
    ├── Vtc/yyyymm # final point values after tracking
    |       └── V-{ty}-{yyyymmddhhTT}-{llll}.csv
    |
    ├── T/  # all-in-one tracking data (Note: netcdf)
    |       ├── T-{ty}-{yyyy}-{llll}.nc  # for long_term=True in Track()
    |       └── T-{ty}-{llll}.nc  # for long_term=False in Track() (default)
    |
    └── ID/  # continuous csv for a specific track whose id is `ID`
        └── {ty}-{l}-{yyyymm}-{ID}.csv

where, ty is L (cyclone) or H (anticyclone), yyyymmddhhTT is timestep, llll is level in 4 digits, and l is level.

Parameter list for Vct data

Names	Description
time	Time.
ty	0 for lows and troughs, 1 for highs and ridges.
lev	Level of the input field.
lat, lon	Central coorditates in latitude and longitude.
valV	Value of input field on the center
valX	Value of the nearest local minimum (maximum) of input field for a low (high).
lonX,latX	Latitude and longitude of the nearest local extremum if any, otherwise this value will be 999.9
So	Optimal slope [m/100 km]. Intensity of depresion (circular geostrophic wind speed).
ro	Optimal radius [r km]. Size of depression (as a radius of its surrounding circulation).
Do	Optimal depth [m]. Vertical depth of depression.
SBG	Background slope [m/100 km].
SBGang	Angle of Background slope vector [radian]. 0 for east.
m, n	Zonal, meridional components of SBG, respectivelly [m/100 km].
SR	Slope ratio. Less (more) than 1.34 tends to correspond to a closed-contour (open-contour) system. See K21 for detail discussions.
ex	Distinction between closed and open systems. 1 (there is a extremum within ro*0.65) for lows/highs 0 for troughs/ridges. cf. ex2 below.
EE	Eccentricity (1 for pure isotropic, smaller values for oval shape).
EEang	Angle of the long axis from east [radian].
XX	Zonal discrete laplacian with a step of ro [m/(100 km)**2]. Small value means the feature has weak zonal concavity. 0.5 might be a good value to exclude sub-tropical large ridges.
ID	Identification number. It is assigned after tracking. ID will be initialized in every new year's day when long_term=True in Track()
MERGE	Merge lysis flag. 0 for being tracked successfully, -1 for soritary lysis, -2 for being merged from someone, -3 for lysis at the end of analysis, -4 for being involved in the secondary process (see Fig. S2 in KH25), other int for the object ID of its merge lysis.
SPLIT	Split genesis flag. 0 for being tracked successfully, -1 for soritary genesis, -2 for being splitting and producing someone, -3 for genesis at the start of analysis, -4 for being involved in the secondary process (see Fig. S2 in KH25), other int for the object ID of its split genesis.
DIST	Moving distance in a timestep [km]. Central difference. When merge/split/genesis/lysis, value will be missing.
SPEED	Moving speed [m/s]. DIST/timestep.
DIR	Moving direction [radian]. 0 for east.
_ DC	Accumulated duration [timestep] including before split.
DU	Duration [hour].
XS	Sequential duration being ex=1 (lows/highs). cf. XSSR below.
QS	Quasi-stational (QS) duration [hour]. The conditions for QS are controlled by the options in Track() as follows: - QS_min_intensity - QS_min_radius - QS_min_overlap_ratio
TOTDIST	Accumulated moving distance [km].
MAX	1 for the maximum development timestep (maximum So).
MAXSo	So when MAX.
exGEN	Closed system genesys (ex changed from 0 to 1 in this timestep).
exLYS	Closed system lysis (ex changed from 1 to 0 in the next timestep).
ex2	Distinction between "sequential" closed and open systems for more than 36 hour (Munoz et al. 2020), i.e., XS >= 36 hour. 1 ("sequential" closed system) 0 (others)
XSSR	Sequential duration being SR<1.34 (theoretical local extrema condition without 8-stencil comparison like ex).
exSR	As with ex2, but it matches XSSR >= 36 hour rather than XS. 1 ("theoretical" and "sequential" closed system) 0 (others)