Metadata-Version: 2.4
Name: colindex2
Version: 2.11.3
Summary: depression detection/tracking schemes
Author-email: Satoru Kasuga <kasugab3621@outlook.com>
License: MIT License
        
        Copyright (c) 2021-2026 satoru kasuga
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://gitlab.com/kasugab3621/colindex2.git
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: polars
Requires-Dist: xarray
Requires-Dist: scipy
Requires-Dist: torch
Requires-Dist: netCDF4
Requires-Dist: h5netcdf
Requires-Dist: matplotlib
Requires-Dist: cartopy
Requires-Dist: threadpoolctl
Dynamic: license-file


[![PyPI version](https://badge.fury.io/py/colindex2.svg)](https://pypi.org/project/colindex2/)

# colindex2

<!--
<div align="left">
<img src="map.png" width="40%">
</div>
-->

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](https://doi.org/10.1175/MWR-D-20-0255.1), [Supplimental Material](https://journals.ametsoc.org/supplemental/journals/mwre/149/9/MWR-D-20-0255.1.xml/10.1175_MWR-D-20-0255.s1.pdf?t:state:client=Db3o/0JSJOfoToVBJ4ILUV2f7FY=:H4sIAAAAAAAAAH2TsW8TMRTGnZSIVKkIjYo6ITEwXyYkEBM0rTj1CJESMbC9u3u5GHz28ey7JAuChQ4MLLAxMDD2X2FkYEMww4SE1An7UhpS9TKc5bN/+r7P79nHP1ljeokxtquJHSpKPMggmqBnIENtaH7L49IgSRCeRip4hNrbExylGSBpro2dHXAU8dAoggT9NBM3D3H+9ffu28s/To7qbCNgrUilmZIW9WPDOsFTKKArQCbdoSEuk7sB2xw7kT6k+Jy9YLWANTOrdvY/ywy7Eyk55klOEAq0c2ftoFDFc69QIk+Ra52jRrtt05yuGRUZthXlRJbvYWYmhu38L9XdW2jZCmy7ZJ5L5vl2LUHqfP/46c+ro9t1VvNZowCR44zY1SXXz9MQ6fXx++utd9/e1BmbZbacTLvYzA0bhrX1RE3vRbZ22rfO5V5j1e6+UgJBfr5BL798OPll7Z78s8tqK2LbpRgZHglcmC/k3Ni6wHdf2iIQGK5kCbqhvYJ1Sizmtma2c1NFsa4gtxw5cG2WY1XBNB3ja13ltr104yBG8wwrwJZtLpdgcKSiCmSzzEP2Vq4zeyQFlzjIw54VqzIrq5qbiaKqw7eWwauQaxHIAamEbKd5gT2uMwHzCridwuwBQmwfQHktz7DmOU0lBGQa+0o+BG4/Y057fkEAl3GIxFE/Lm9/ACGK9Z0K13aqh2PIhTlQlIKpAHfK4hXAhXtPC3T9FYrHAZfP1jLDPDTciKqGXXHMyAHnjvgXTbQg89MEAAA=) 

- Kasuga, S., and M. Honda, 2025: Climatology of Cutoff Lows Approaching Japan. *SOLA*, **21**, 329-333, [https://doi.org/10.2151/sola.2025-049](https://doi.org/10.2151/sola.2025-049), [Supplimental Material](https://www.jstage.jst.go.jp/article/sola/21/0/21_2025-049/_supplement/_download/21_2025-049_1.pdf) 


<!--
Site above references when you publish papers using this package.
:warning: The tracking scheme is underconstruction and its definition may be changed unnoticed. The relatively stabe versions are v2.7.6, and v2.8.1 See Tags and CHANGELOG. (edit: 2025.4.30)
-->

# Install

```
pip install colindex2
```
Dependecies are...

```
numpy pandas polars pytorch scipy xarray netCDF4 h5netcdf matplotlib cartopy threadpoolctl
```

<!--
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](https://www.anaconda.com/blog/using-pip-in-a-conda-environment).
-->


# Tutorial
Try [quick tutorial](colindex2_tutorial.ipynb)

<!--
# Table of contents
[[_TOC_]]
-->

# How to execute
Two different ways are available using (1) python functions and (2) command lines

## (1) Python functions -> [documents](https://kasugab3621.gitlab.io/colindex2/index.html)

## (2) Shell commands

Add `-h` to see documets.

- 1. Generate data_settings.py

```bash
gen_data_settings
```

- 2. Edit [data_settings.py](colindex2/data_settings.py)

- 3. Run detection

```bash
detect z.nc
```

- 4. Run tracking

```bash
track
```

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

```bash
detect z.nc -track
```

<!--
- Draw maps to check tracking data and AS (netcdf output only)

```bash
$ draw_map z.nc ./d01 L 300 nps
```
-->

- 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, <br> `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. <br>`1` (there is a extremum within `ro`\*0.65) for lows/highs <br> `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. <br>`0` for being tracked successfully, <br>`-1` for soritary lysis, <br>`-2` for being merged from someone, <br>`-3` for lysis at the end of analysis, <br>`-4` for being involved in the secondary process (see Fig. S2 in KH25), <br>`other int` for the object ID of its merge lysis. |
| SPLIT | Split genesis flag. <br>`0` for being tracked successfully, <br>`-1` for soritary genesis, <br>`-2` for being splitting and producing someone, <br>`-3` for genesis at the start of analysis, <br>`-4` for being involved in the secondary process (see Fig. S2 in KH25), <br>`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: <br> - `QS_min_intensity` <br> - `QS_min_radius` <br> - `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.<br>`1` ("sequential" closed system)<br> `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`.<br>`1` ("theoretical" and "sequential" closed system)<br> `0` (others) |


<!--
-->
<!--
| MEDDIST | Median moving distance in a track [km]. |
| MAXXS | Maximum duration of XS in a track (XS can be scored in multiple sequences). |
| MAXQS5 | Maximum duration of QS5 in a track. |
| MAXQS7 | Maximum duration of QS7 in a track. |
-->

