Metadata-Version: 2.4
Name: colindex2
Version: 2.11.0
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: xarray
Requires-Dist: scipy
Requires-Dist: torch
Requires-Dist: netCDF4
Requires-Dist: h5netcdf
Requires-Dist: matplotlib
Requires-Dist: cartopy
Dynamic: license-file


# colindex2

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

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


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

### 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) (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](https://doi.org/10.2151/sola.2025-049) (KH25)  


<!--
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 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](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
Note that python3 and requirements must be installed.  

Add `-h` to see their documets.

- 1. Generate data_settings.py

```bash
gen_data_settings
```

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

- 3. Run detection

```bash
detect z.nc
```

- 4. Run tracking

```bash
track
```

or, you can do doth 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
```

# 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, <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. |
| 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. <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 integers` for the object ID of its merge lysis. |
| SPLIT | Split genesis flag. <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 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: <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). |

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

