colindex2 2.11.0

depression detection/tracking schemes

colindex2

A python package for atmospheric depression detection and tracking. The main target is to capture upper tropospheric disturbances such as cutoff lows from preexisting trough stage, with their seamless transitions of basic variables such as intensity, size, duration, etc..

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 (K21)

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

Install

pip install colindex2

Dependecies are...

numpy pandas pytorch scipy xarray netCDF4 h5netcdf matplotlib cartopy  

If you use anaconda environment, prepare the dependencies using conda in advance and then install colindex2 using conda's pip, as recommended by anaconda.com.

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

Note that python3 and requirements must be installed.

Add -h to see their 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 as follows:

detect z.nc -track

• Find and make each tracking data

find_track ./d01 L 300 a

Directory structure of outputs

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

where, ty is L or H, 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.
EE	Eccentricity (1 for pure isotropic, smaller values for oval shape).
EEang	Angle of the long axis from east [rad].
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. This can be larger than number of resultant detections since it includes noises.
MERGE	Merge lysis flag. -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 integers for the object ID of its merge lysis.
SPLIT	Split genesis flag. -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 integers 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).
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).