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).

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 scipy xarray matplotlib cartopy

Tutorial

Try quick tutorial

How to execute

Two different ways are available using python functions or command lines

Python functions: documents

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

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
    |       ├── T-{ty}-{yyyy}-{llll}.csv  # for long_term=True in Track()
    |       └── T-{ty}-{llll}.csv  # 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 and T outputs