PyStormTracker 0.2.1__py3-none-any.whl

pystormtracker/__init__.py

@@ -0,0 +1,4 @@
+from .models import Center, Grid, Tracks
+from .simple import SimpleDetector, SimpleLinker
+
+__all__ = ["Center", "Grid", "SimpleDetector", "SimpleLinker", "Tracks"]

pystormtracker/models/__init__.py

@@ -0,0 +1,5 @@
+from .center import Center
+from .grid import Grid
+from .tracks import Tracks
+
+__all__ = ["Center", "Grid", "Tracks"]

pystormtracker/models/center.py

@@ -0,0 +1,58 @@
+import math
+from typing import Any
+
+
+class Center:
+    R: float = 6367.0
+    DEGTORAD: float = math.pi / 180.0
+
+    def __init__(self, time: Any, lat: float, lon: float, var: Any) -> None:
+        self.time = time
+        self.lat = lat
+        self.lon = lon
+        self.var = var
+
+    def __repr__(self) -> str:
+        return str(self.var)
+
+    def __str__(self) -> str:
+        return f"[time={self.time}, lat={self.lat}, lon={self.lon}, var={self.var}]"
+
+    def abs_dist(self, center: "Center") -> float:
+        """Haversine formula for calculating the great circle distance"""
+
+        if not isinstance(center, Center):
+            raise TypeError("must be compared with a Center object")
+
+        dlat = center.lat - self.lat
+        dlon = center.lon - self.lon
+
+        return (
+            self.R
+            * 2
+            * math.asin(
+                math.sqrt(
+                    math.sin(dlat / 2 * self.DEGTORAD) ** 2
+                    + math.cos(self.lat * self.DEGTORAD)
+                    * math.cos(center.lat * self.DEGTORAD)
+                    * math.sin(dlon / 2 * self.DEGTORAD) ** 2
+                )
+            )
+        )
+
+    def lat_dist(self, center: "Center") -> float:
+        if not isinstance(center, Center):
+            raise TypeError("must be compared with a Center object")
+
+        dlat = center.lat - self.lat
+
+        return self.R * dlat * self.DEGTORAD
+
+    def lon_dist(self, center: "Center") -> float:
+        if not isinstance(center, Center):
+            raise TypeError("must be compared with a Center object")
+
+        avglat = (self.lat + center.lat) / 2
+        dlon = center.lon - self.lon
+
+        return self.R * dlon * self.DEGTORAD * math.cos(avglat * self.DEGTORAD)

pystormtracker/models/grid.py

@@ -0,0 +1,40 @@
+from abc import ABCMeta, abstractmethod
+from typing import Any, Literal
+
+from .center import Center
+
+
+class Grid(metaclass=ABCMeta):
+    @abstractmethod
+    def get_var(self, chart: int | tuple[int, int] | None = None) -> Any:
+        raise NotImplementedError
+
+    @abstractmethod
+    def get_time(self) -> Any:
+        raise NotImplementedError
+
+    @abstractmethod
+    def get_time_obj(self) -> Any:
+        raise NotImplementedError
+
+    @abstractmethod
+    def get_lat(self) -> Any:
+        raise NotImplementedError
+
+    @abstractmethod
+    def get_lon(self) -> Any:
+        raise NotImplementedError
+
+    @abstractmethod
+    def split(self, num: int) -> list["Grid"]:
+        raise NotImplementedError
+
+    @abstractmethod
+    def detect(
+        self,
+        size: int = 5,
+        threshold: float = 0.0,
+        chart_buffer: int = 400,
+        minmaxmode: Literal["min", "max"] = "min",
+    ) -> list[list[Center]]:
+        raise NotImplementedError

pystormtracker/models/tracks.py

@@ -0,0 +1,29 @@
+from collections.abc import Iterator
+from typing import Any
+
+from .center import Center
+
+
+class Tracks:
+    def __init__(self) -> None:
+        self._tracks: list[list[Center]] = []
+        self.head: list[int] = []
+        self.tail: list[int] = []
+        self.tstart: Any | None = None
+        self.tend: Any | None = None
+        self.dt: Any | None = None
+
+    def __getitem__(self, index: int) -> list[Center]:
+        return self._tracks[index]
+
+    def __setitem__(self, index: int, value: list[Center]) -> None:
+        self._tracks[index] = value
+
+    def __iter__(self) -> Iterator[list[Center]]:
+        return iter(self._tracks)
+
+    def __len__(self) -> int:
+        return len(self._tracks)
+
+    def append(self, obj: list[Center]) -> None:
+        self._tracks.append(obj)

pystormtracker/simple/__init__.py

@@ -0,0 +1,4 @@
+from .detector import SimpleDetector
+from .linker import SimpleLinker
+
+__all__ = ["SimpleDetector", "SimpleLinker"]

pystormtracker/simple/detector.py

@@ -0,0 +1,315 @@
+from typing import Any, Literal
+
+import netCDF4
+import numpy as np
+from scipy.ndimage import generic_filter, laplace
+
+from ..models.center import Center
+from ..models.grid import Grid
+
+
+class SimpleDetector(Grid):
+    def __init__(
+        self, pathname: str, varname: str, trange: tuple[int, int] | None = None
+    ) -> None:
+
+        self.pathname = pathname
+        self.varname = varname
+        self.trange = trange
+
+        self._open_file: bool = False
+        self._var: Any = None
+        self._time: Any = None
+        self._lat: Any = None
+        self._lon: Any = None
+
+        self.f: Any = None
+        self.time: Any = None
+        self.lat: Any = None
+        self.lon: Any = None
+
+    def _init(self) -> None:
+        if self._open_file is False:
+            self._open_file = True
+            self.f = netCDF4.Dataset(self.pathname, "r")
+
+            # Dimension of var is time, lat, lon
+            self._var = self.f.variables[self.varname]
+            # Disable auto mask and scale as it may mask valid SLP values in some files
+            self._var.set_auto_maskandscale(False)
+
+            self._time = self.f.variables["time"]
+
+            if "latitude" in self.f.variables:
+                self._lat = self.f.variables["latitude"]
+            elif "lat" in self.f.variables:
+                self._lat = self.f.variables["lat"]
+            else:
+                raise KeyError(
+                    "Neither 'latitude' nor 'lat' found in NetCDF variables."
+                )
+
+            if "longitude" in self.f.variables:
+                self._lon = self.f.variables["longitude"]
+            elif "lon" in self.f.variables:
+                self._lon = self.f.variables["lon"]
+            else:
+                raise KeyError(
+                    "Neither 'longitude' nor 'lon' found in NetCDF variables."
+                )
+
+            self.time = None
+            self.lat = None
+            self.lon = None
+
+    def get_var(self, chart: int | tuple[int, int] | None = None) -> Any:
+
+        if self.trange is not None:
+            if self.trange[0] >= self.trange[1]:
+                return None
+
+        if chart is not None:
+            if isinstance(chart, tuple):
+                if (
+                    len(chart) != 2
+                    or not isinstance(chart[0], int)
+                    or not isinstance(chart[1], int)
+                ):
+                    raise TypeError("chart must be a tuple of two integers")
+            elif not isinstance(chart, int):
+                raise TypeError("chart must be an integer or tuple")
+
+            if self.trange is not None:
+                if isinstance(chart, int):
+                    if chart < 0 or chart >= self.trange[1] - self.trange[0]:
+                        raise IndexError("chart is out of bound of trange")
+                if isinstance(chart, tuple):
+                    if chart[0] == chart[1]:
+                        return None
+                    if chart[0] > chart[1]:
+                        raise IndexError("chart[1] must be larger than chart[0]")
+                    if chart[0] < 0 or chart[0] > self.trange[1] - self.trange[0]:
+                        raise IndexError("chart[0] is out of bound of trange")
+                    if chart[1] < 0 or chart[1] > self.trange[1] - self.trange[0]:
+                        raise IndexError("chart[1] is out of bound of trange")
+
+        self._init()
+
+        if isinstance(chart, int):
+            if self.trange is None:
+                return self._var[chart, :, :]
+            else:
+                return self._var[self.trange[0] + chart, :, :]
+        elif isinstance(chart, tuple):
+            if self.trange is None:
+                return self._var[chart[0] : chart[1], :, :]
+            else:
+                return self._var[
+                    self.trange[0] + chart[0] : self.trange[0] + chart[1], :, :
+                ]
+        else:
+            return self._var[:]
+
+    def get_time(self) -> Any:
+
+        if self.trange is not None:
+            if self.trange[0] >= self.trange[1]:
+                return None
+
+        self._init()
+        if self.time is None:
+            if self.trange is None:
+                self.time = self._time[:]
+            else:
+                self.time = self._time[self.trange[0] : self.trange[1]]
+        return self.time
+
+    def get_time_obj(self) -> Any:
+        self._init()
+        return self._time
+
+    def get_lat(self) -> Any:
+
+        self._init()
+        if self.lat is None:
+            self.lat = self._lat[:]
+        return self.lat
+
+    def get_lon(self) -> Any:
+
+        self._init()
+        if self.lon is None:
+            self.lon = self._lon[:]
+        return self.lon
+
+    def split(self, num: int) -> list["Grid"]:
+
+        if not isinstance(num, int):
+            raise TypeError("number to split must be an integer")
+
+        if self._open_file is False:
+            if self.trange is not None:
+                time_len = self.trange[1] - self.trange[0]
+                tstart = self.trange[0]
+            else:
+                f = netCDF4.Dataset(self.pathname, "r")
+                time_len = f.dimensions["time"].size
+                f.close()
+                tstart = 0
+
+            chunk_size = time_len // num
+            remainder = time_len % num
+
+            tranges = [
+                (
+                    tstart + i * chunk_size + remainder * i // num,
+                    tstart + (i + 1) * chunk_size + remainder * (i + 1) // num,
+                )
+                for i in range(num)
+            ]
+
+            return [
+                SimpleDetector(self.pathname, self.varname, trange=it) for it in tranges
+            ]
+
+        else:
+            raise RuntimeError(
+                "SimpleDetector must not be initialized before running split()"
+            )
+
+    def _local_extrema_func(
+        self,
+        buffer: np.ndarray,
+        size: int,
+        threshold: float,
+        minmaxmode: Literal["min", "max"],
+    ) -> bool:
+
+        half_size = size // 2
+
+        search_window = buffer.reshape((size, size))
+        origin = (half_size, half_size)
+
+        center_val = search_window[origin]
+
+        # If the center value is masked, it cannot be an extrema
+        if np.ma.is_masked(center_val):
+            return False
+
+        if threshold == 0.0:
+            if minmaxmode == "min":
+                return bool(center_val == search_window.min())
+            elif minmaxmode == "max":
+                return bool(center_val == search_window.max())
+        elif center_val == search_window.min():
+            if minmaxmode == "min":
+                # At least 8 of values in buffer should be larger than threshold
+                return bool(sorted(buffer)[8] - center_val > threshold)
+        elif center_val == search_window.max():
+            if minmaxmode == "max":
+                return bool(sorted(buffer)[0] - center_val < -1 * threshold)
+        return False
+
+    def _local_extrema_filter(
+        self,
+        input_arr: np.ndarray,
+        size: int,
+        threshold: float = 0.0,
+        minmaxmode: Literal["min", "max"] = "min",
+    ) -> np.ndarray:
+
+        if size % 2 != 1:
+            raise ValueError("size must be an odd number")
+
+        half_size = size // 2
+
+        output = generic_filter(
+            input_arr,
+            self._local_extrema_func,
+            size=size,
+            mode="wrap",
+            extra_keywords={
+                "size": size,
+                "threshold": threshold,
+                "minmaxmode": minmaxmode,
+            },
+        )
+
+        # Mask the extreme latitudes
+        output[:half_size, :] = 0.0
+        output[-half_size:, :] = 0.0
+
+        return np.asarray(output)
+
+    def _local_max_laplace(self, buffer: np.ndarray, size: int) -> bool:
+        origin = (size * size) // 2
+        return bool(buffer[origin] and buffer[origin] == buffer.max())
+
+    def _remove_dup_laplace(
+        self, data: np.ndarray, mask: np.ndarray, size: int = 5
+    ) -> np.ndarray:
+        laplacian = np.multiply(laplace(data, mode="wrap"), mask)
+
+        return np.asarray(
+            generic_filter(
+                laplacian,
+                self._local_max_laplace,
+                size=size,
+                mode="wrap",
+                extra_keywords={"size": size},
+            )
+        )
+
+    def detect(
+        self,
+        size: int = 5,
+        threshold: float = 0.0,
+        chart_buffer: int = 400,
+        minmaxmode: Literal["min", "max"] = "min",
+    ) -> list[list[Center]]:
+        """Returns a list of list of Center's"""
+
+        if self.trange is not None and self.trange[0] >= self.trange[1]:
+            return []
+
+        time = self.get_time()
+        lat = self.get_lat()
+        lon = self.get_lon()
+
+        centers = []
+
+        var: Any = None
+
+        num_steps = len(time)
+        for it, t in enumerate(time):
+            ibuffer = it % chart_buffer
+            if ibuffer == 0:
+                var = self.get_var(chart=(it, min(it + chart_buffer, num_steps)))
+
+            if var is not None:
+                chart = var[ibuffer, :, :]
+
+                # Fill masked values so they aren't detected as extrema
+                if minmaxmode == "min":
+                    filled_chart = np.ma.filled(chart, fill_value=np.inf)
+                else:
+                    filled_chart = np.ma.filled(chart, fill_value=-np.inf)
+
+                extrema = self._local_extrema_filter(
+                    filled_chart, size, threshold=threshold, minmaxmode=minmaxmode
+                )
+
+                # Ensure we don't detect centers on originally masked pixels
+                if np.ma.is_masked(chart):
+                    extrema[chart.mask] = 0
+
+                extrema = self._remove_dup_laplace(filled_chart, extrema, size=5)
+
+                center_list = [
+                    Center(t, float(lat[i]), float(lon[j]), chart[i, j])
+                    for i, j in np.transpose(extrema.nonzero())
+                ]
+                print(f"Step {it + 1}/{num_steps}: Found {len(center_list)} centers")
+                centers.append(center_list)
+
+        return centers

pystormtracker/simple/linker.py

@@ -0,0 +1,104 @@
+from ..models.center import Center
+from ..models.tracks import Tracks
+
+
+class SimpleLinker:
+    def __init__(self, threshold: float = 500.0) -> None:
+        self.threshold = threshold
+
+    def match_center(self, tracks: Tracks, centers: list[Center]) -> list[int | None]:
+        ends = [tracks[i][-1] for i in tracks.tail]
+
+        dforward: list[dict[int, float]] = [{} for _ in range(len(ends))]
+        dbackward: list[dict[int, float]] = [{} for _ in range(len(centers))]
+
+        for ic1, c1 in enumerate(ends):
+            for ic2, c2 in enumerate(centers):
+                dist = c1.abs_dist(c2)
+                if dist < self.threshold:
+                    dforward[ic1][ic2] = dist
+                    dbackward[ic2][ic1] = dist
+
+        matched: list[int | None] = [None for _ in range(len(centers))]
+
+        while True:
+            has_match = False
+
+            for i, db in enumerate(dbackward):
+                if matched[i] is None and len(db) > 0:
+                    iforward = min(db, key=db.get)  # type: ignore
+                    di = dforward[iforward]
+
+                    if min(di, key=di.get) == i:  # type: ignore
+                        matched[i] = iforward
+
+                        db.clear()
+                        for j in dbackward:
+                            if iforward in j:
+                                del j[iforward]
+                        di.clear()
+
+                        for j in dforward:
+                            if i in j:
+                                del j[i]
+
+                        has_match = True
+
+            if has_match is False:
+                break
+
+        return [tracks.tail[i] if i is not None else None for i in matched]
+
+    def match_track(self, tracks1: Tracks, tracks2: Tracks) -> list[int | None]:
+        centers = [tracks2[i][0] for i in tracks2.head]
+        return self.match_center(tracks1, centers)
+
+    def append_center(self, tracks: Tracks, centers: list[Center]) -> None:
+        new_tail: list[int] = []
+
+        matched_index = self.match_center(tracks, centers)
+
+        for i, d in enumerate(matched_index):
+            if tracks.tstart is None:
+                tracks.append([centers[i]])
+                tracks.head.append(len(tracks) - 1)
+                new_tail.append(len(tracks) - 1)
+            elif d is None or (
+                tracks.tend is not None
+                and tracks.dt is not None
+                and centers[0].time - tracks.dt > tracks.tend
+            ):
+                tracks.append([centers[i]])
+                new_tail.append(len(tracks) - 1)
+            else:
+                tracks[d].append(centers[i])
+                new_tail.append(d)
+
+        tracks.tail = new_tail
+
+        tracks.tend = centers[0].time
+        if tracks.tstart is None:
+            tracks.tstart = centers[0].time
+        elif tracks.dt is None:
+            tracks.dt = tracks.tend - tracks.tstart
+
+    def extend_track(self, tracks1: Tracks, tracks2: Tracks) -> None:
+        new_tail: list[int] = []
+
+        matched_index = self.match_track(tracks1, tracks2)
+        matched_dict = {d: matched_index[i] for i, d in enumerate(tracks2.head)}
+        tail_dict = dict.fromkeys(tracks2.tail)
+
+        for i, d in enumerate(tracks2):
+            match_idx = matched_dict.get(i)
+            if match_idx is not None:
+                tracks1[match_idx].extend(d)
+                if i in tail_dict:
+                    new_tail.append(match_idx)
+            else:
+                tracks1.append(d)
+                if i in tail_dict:
+                    new_tail.append(len(tracks1) - 1)
+
+        tracks1.tail = new_tail
+        tracks1.tend = tracks2.tend

pystormtracker/stormtracker.py

@@ -0,0 +1,244 @@
+import csv
+import os
+import sys
+import timeit
+from argparse import ArgumentParser, Namespace
+from typing import Any, Literal
+
+import netCDF4
+import numpy as np
+
+from .models import Center, Grid, Tracks
+from .simple import SimpleDetector, SimpleLinker
+
+Backend = Literal["serial", "mpi", "dask"]
+
+
+def export_to_csv(
+    tracks: Tracks, outfile: str, grid: Grid, decimal_places: int = 4
+) -> None:
+    """Exports detected tracks to a user-friendly CSV file."""
+    time_obj = grid.get_time_obj()
+    units = getattr(time_obj, "units", "")
+    calendar = getattr(time_obj, "calendar", "standard")
+
+    if not outfile.endswith(".csv"):
+        outfile += ".csv"
+
+    with open(outfile, "w", newline="") as f:
+        writer = csv.writer(f)
+        writer.writerow(["track_id", "time", "lat", "lon", "var"])
+        for i, track in enumerate(tracks):
+            for center in track:
+                try:
+                    dt = netCDF4.num2date(center.time, units=units, calendar=calendar)
+                    # dt can be a cftime.datetime or a standard datetime
+                    time_val = dt.strftime("%Y-%m-%d %H:%M:%S")  # type: ignore
+                except Exception:
+                    time_val = str(center.time)
+
+                if center.var is None or np.ma.is_masked(center.var):
+                    var_val = "--"
+                else:
+                    var_val = f"{float(center.var):.{decimal_places}f}"
+                writer.writerow([i, time_val, center.lat, center.lon, var_val])
+
+
+def _detect_serial(
+    infile: str, varname: str, trange: tuple[int, int] | None, mode: str
+) -> tuple[list[list[Center]], Grid]:
+    grid = SimpleDetector(pathname=infile, varname=varname, trange=trange)
+    return grid.detect(minmaxmode=mode), grid  # type: ignore
+
+
+def _detect_mpi(
+    infile: str, varname: str, trange: tuple[int, int] | None, mode: str
+) -> tuple[list[list[Center]], Grid, Any]:
+    from mpi4py import MPI
+
+    comm = MPI.COMM_WORLD
+    rank = comm.Get_rank()
+    size = comm.Get_size()
+    root = 0
+
+    if rank == root:
+        grid_obj = SimpleDetector(pathname=infile, varname=varname, trange=trange)
+        grids: list[Grid] | None = grid_obj.split(size)
+    else:
+        grids = None
+
+    grid = comm.scatter(grids, root=root)
+    return grid.detect(minmaxmode=mode), grid, comm
+
+
+def _detect_dask(
+    infile: str,
+    varname: str,
+    trange: tuple[int, int] | None,
+    mode: str,
+    n_workers: int | None,
+) -> tuple[list[list[Center]], Grid]:
+    import dask
+    from distributed import Client, LocalCluster
+
+    if n_workers is None or n_workers <= 0:
+        n_workers = os.cpu_count() or 4
+
+    grid_obj = SimpleDetector(pathname=infile, varname=varname, trange=trange)
+    grids = grid_obj.split(n_workers)
+
+    with LocalCluster(
+        n_workers=n_workers, threads_per_worker=1
+    ) as cluster, Client(cluster):  # type: ignore
+        delayed_results = [
+            dask.delayed(g.detect)(minmaxmode=mode) for g in grids  # type: ignore
+        ]
+        results = dask.compute(*delayed_results)  # type: ignore
+
+    # Flatten results from chunks
+    flattened_results: list[list[Center]] = []
+    for chunk in results:
+        flattened_results.extend(chunk)
+
+    return flattened_results, grid_obj
+
+
+def _link_centers(centers: list[list[Center]]) -> Tracks:
+    tracks = Tracks()
+    linker = SimpleLinker()
+    for step_centers in centers:
+        linker.append_center(tracks, step_centers)
+    return tracks
+
+
+def _combine_mpi_tracks(tracks: Tracks, comm: Any) -> Tracks:
+    rank = comm.Get_rank()
+    size = comm.Get_size()
+    linker = SimpleLinker()
+
+    nstripe = 2
+    while nstripe <= size:
+        if rank % nstripe == nstripe // 2:
+            comm.send(tracks, dest=rank - nstripe // 2, tag=nstripe)
+        elif rank % nstripe == 0 and rank + nstripe // 2 < size:
+            tracks_recv = comm.recv(source=rank + nstripe // 2, tag=nstripe)
+            linker.extend_track(tracks, tracks_recv)
+        nstripe *= 2
+    return tracks
+
+
+def run_tracker(
+    infile: str,
+    varname: str,
+    outfile: str,
+    trange: tuple[int, int] | None = None,
+    mode: Literal["min", "max"] = "min",
+    backend: Backend = "dask",
+    n_workers: int | None = None,
+) -> None:
+    """Orchestrates the storm tracking process."""
+    timer: dict[str, float] = {}
+    use_mpi = backend == "mpi"
+    use_dask = backend == "dask"
+
+    rank = 0
+    if use_mpi:
+        from mpi4py import MPI
+
+        rank = MPI.COMM_WORLD.Get_rank()
+
+    if rank == 0:
+        timer["detector"] = timeit.default_timer()
+
+    # Detection Phase
+    comm = None
+    if use_mpi:
+        centers, grid, comm = _detect_mpi(infile, varname, trange, mode)
+    elif use_dask:
+        centers, grid = _detect_dask(infile, varname, trange, mode, n_workers)
+    else:
+        centers, grid = _detect_serial(infile, varname, trange, mode)
+
+    if use_mpi and comm is not None:
+        comm.Barrier()
+
+    if rank == 0:
+        timer["detector"] = timeit.default_timer() - timer["detector"]
+        timer["linker"] = timeit.default_timer()
+
+    # Linking Phase
+    tracks = _link_centers(centers)
+
+    # Consolidation Phase
+    if use_mpi and comm is not None:
+        timer["combiner"] = timeit.default_timer()
+        tracks = _combine_mpi_tracks(tracks, comm)
+        timer["combiner"] = timeit.default_timer() - timer["combiner"]
+
+    # Export Phase
+    if rank == 0:
+        timer["linker"] = timeit.default_timer() - timer["linker"]
+
+        print(f"Detector time: {timer['detector']:.4f}s")
+        print(f"Linker time: {timer['linker']:.4f}s")
+        if "combiner" in timer:
+            print(f"Combiner time: {timer['combiner']:.4f}s")
+
+        num_tracks = len(
+            [t for t in tracks if len(t) >= 8 and t[0].abs_dist(t[-1]) >= 1000.0]
+        )
+        print(f"Number of long tracks (>= 8 steps, >= 1000km): {num_tracks}")
+
+        export_to_csv(tracks, outfile, grid)
+        final_outfile = outfile if outfile.endswith(".csv") else f"{outfile}.csv"
+        print(f"Results exported to {final_outfile}")
+
+
+def parse_args() -> Namespace:
+    """Parses command line arguments."""
+    parser = ArgumentParser(description="PyStormTracker: A tool for tracking storms.")
+    parser.add_argument("-i", "--input", required=True, help="Input NetCDF file.")
+    parser.add_argument("-v", "--var", required=True, help="Variable to track.")
+    parser.add_argument("-o", "--output", required=True, help="Output CSV file.")
+    parser.add_argument("-n", "--num", type=int, help="Number of time steps.")
+    parser.add_argument(
+        "-m", "--mode", choices=["min", "max"], default="min", help="Detection mode."
+    )
+    parser.add_argument(
+        "-b",
+        "--backend",
+        choices=["serial", "mpi", "dask"],
+        default="dask",
+        help="Parallel backend. Default is 'dask'.",
+    )
+    parser.add_argument(
+        "-w",
+        "--workers",
+        type=int,
+        default=None,
+        help="Number of workers for Dask. Defaults to number of CPU cores.",
+    )
+    return parser.parse_args()
+
+
+def main() -> None:
+    args = parse_args()
+    trange = (0, args.num) if args.num is not None else None
+
+    try:
+        run_tracker(
+            infile=args.input,
+            varname=args.var,
+            outfile=args.output,
+            trange=trange,
+            mode=args.mode,
+            backend=args.backend,
+            n_workers=args.workers,
+        )
+    except Exception as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

pystormtracker-0.2.1.dist-info/METADATA

@@ -0,0 +1,146 @@
+Metadata-Version: 2.4
+Name: PyStormTracker
+Version: 0.2.1
+Summary: A Parallel Object-Oriented Cyclone Tracker in Python
+Project-URL: Homepage, https://github.com/mwyau/PyStormTracker
+Project-URL: Repository, https://github.com/mwyau/PyStormTracker.git
+Project-URL: Issues, https://github.com/mwyau/PyStormTracker/issues
+Author-email: "Albert M. W. Yau" <albert@mwyau.com>
+Maintainer-email: "Albert M. W. Yau" <albert@mwyau.com>
+License: BSD-3-Clause
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
+Requires-Python: >=3.10
+Requires-Dist: dask>=2024.2.0
+Requires-Dist: distributed>=2024.2.0
+Requires-Dist: netcdf4>=1.6.5
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: scipy>=1.10.0
+Provides-Extra: dev
+Requires-Dist: mpi4py>=3.1.5; extra == 'dev'
+Requires-Dist: mypy>=1.9.0; extra == 'dev'
+Requires-Dist: netcdf4>=1.6.5; extra == 'dev'
+Requires-Dist: pandas>=2.2.0; extra == 'dev'
+Requires-Dist: pre-commit>=3.7.0; extra == 'dev'
+Requires-Dist: pytest>=8.1.1; extra == 'dev'
+Requires-Dist: ruff>=0.3.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# PyStormTracker
+
+[![DOI](https://zenodo.org/badge/36328800.svg)](https://doi.org/10.5281/zenodo.18764813)
+
+PyStormTracker provides the implementation of the "Simple Tracker" algorithm used for cyclone trajectory analysis in **Yau and Chang (2020)**. It was originally developed at the **National Center for Atmospheric Research (NCAR)** as part of the **2015 Summer Internships in Parallel Computational Science (SIParCS)** program, utilizing a task-parallel strategy with temporal decomposition and a tree reduction algorithm to process large climate datasets.
+
+## Features
+
+- **Modern Python 3 Support**: Fully migrated from Python 2 with comprehensive type hints.
+- **Flexible Data Support**: Works with `netCDF4` and handles various coordinate naming conventions (`lat`/`lon` vs `latitude`/`longitude`).
+- **Parallel Backends**:
+  - **Dask (Default)**: Automatically scales to all available CPU cores on local machines.
+  - **MPI**: Supports distributed execution via `mpi4py`.
+  - **Serial**: Standard sequential execution for smaller datasets or debugging.
+- **Robust Detection**: Handles masked/missing data correctly and includes automated unit/integration tests.
+- **User-Friendly Output**: Results are exported directly to CSV with readable datetime strings and formatted numeric values.
+
+## Technical Methodology
+
+PyStormTracker treats meteorological fields as 2D images and leverages `scipy.ndimage` for robust feature detection:
+
+- **Local Extrema Detection**: Uses `generic_filter` with a sliding window (default 5x5) to identify local minima (cyclones) or maxima (anticyclones/vorticity).
+- **Intensity & Refinement**: Applies the **Laplacian operator** (`laplace`) to measure the "sharpness" of the field at each detected center point. This is used to resolve duplicates and ensure only the most physically intense point is kept when multiple adjacent pixels are flagged.
+- **Spherical Continuity**: Utilizes `mode='wrap'` for all filters to correctly handle periodic boundaries across the Prime Meridian, enabling seamless tracking across the entire globe.
+- **Heuristic Linking**: Implements a nearest-neighbor linking strategy to connect detected centers into trajectories across successive time steps.
+
+## Installation
+
+### Prerequisites
+- Python 3.10+
+- (Optional) MS-MPI or OpenMPI for MPI support.
+
+### From PyPI (Recommended)
+You can install the latest stable version of PyStormTracker directly from PyPI:
+```bash
+pip install PyStormTracker
+```
+
+### From Source
+1. Clone the repository:
+   ```bash
+   git clone https://github.com/mwyau/PyStormTracker.git
+   cd PyStormTracker
+   ```
+
+2. Install the package in editable mode:
+   ```bash
+   pip install -e .
+   ```
+
+## Usage
+
+Once installed, you can use the `stormtracker` command directly:
+
+```bash
+stormtracker -i data/test/slp.2012.nc -v slp -o my_tracks
+```
+
+### Command Line Arguments
+
+| Argument | Short | Description |
+| :--- | :--- | :--- |
+| `--input` | `-i` | **Required.** Path to the input NetCDF file. |
+| `--var` | `-v` | **Required.** Variable name to track (e.g., `slp`, `vo`). |
+| `--output` | `-o` | **Required.** Path to the output CSV file (appends `.csv` if missing). |
+| `--num` | `-n` | Number of time steps to process. |
+| `--mode` | `-m` | `min` (default) for low pressure, `max` for vorticity/high pressure. |
+| `--backend` | `-b` | `dask` (default), `serial`, or `mpi`. |
+| `--workers` | `-w` | Number of Dask workers (defaults to CPU core count). |
+
+### Examples
+
+**Run with Dask (Auto-detected cores):**
+```bash
+stormtracker -i input.nc -v slp -o tracks
+```
+
+**Run with MPI (Distributed):**
+```bash
+mpiexec -n 4 stormtracker -i input.nc -v slp -o tracks -b mpi
+```
+
+## Project Structure
+
+- `src/pystormtracker/models/`: Data structures (`Center`, `Grid`, `Tracks`).
+- `src/pystormtracker/simple/`: Implementation of the Simple Tracker logic (`SimpleDetector`, `SimpleLinker`).
+- `src/pystormtracker/stormtracker.py`: CLI orchestration and parallel backends.
+
+## Testing
+
+Run the full test suite (unit and integration tests) using `pytest`:
+
+```bash
+pytest
+```
+
+## Citations
+
+If you use this software in your research, please cite the following:
+
+- **Yau, A. M. W., and E. K. M. Chang**, 2020: Finding Storm Track Activity Metrics That Are Highly Correlated with Weather Impacts. Part I: Frameworks for Evaluation and Accumulated Track Activity. *J. Climate*, **33**, 10169–10186, https://doi.org/10.1175/JCLI-D-20-0393.1.   
+
+- **Yau, A. M. W.**, 2026: mwyau/PyStormTracker. *Zenodo*, https://doi.org/10.5281/zenodo.18764813.
+
+## References
+
+ - **Yau, A. M. W., K. Paul and J. Dennis**, 2016: PyStormTracker: A Parallel Object-Oriented Cyclone Tracker in Python. *96th American Meteorological Society Annual Meeting*, New Orleans, LA. *Zenodo*, https://doi.org/10.5281/zenodo.18868625.
+
+## License
+
+This project is licensed under the terms found in the `LICENSE` file.

pystormtracker-0.2.1.dist-info/RECORD

@@ -0,0 +1,14 @@
+pystormtracker/__init__.py,sha256=jlK08FvQMrsH73lCnjX0UBIvdVLZqQFDap7YZw5Iz-k,164
+pystormtracker/stormtracker.py,sha256=WzXQGfnrCSBBYPUSYu6DiDW0Bj2ImrjLdjrsWxoHXFk,7549
+pystormtracker/models/__init__.py,sha256=ag5M_Ux68Qh3UJOyUJUvyfKIfMxYCCg4mH38DWSQUWc,117
+pystormtracker/models/center.py,sha256=4T29JuOag7VSs56I8tIyRkaw6s0wyIZ96j8uk3ZIaYc,1735
+pystormtracker/models/grid.py,sha256=prkkvODHukgL2A-R3IYGDWpwkXuLb6QiMAaJq8bo720,962
+pystormtracker/models/tracks.py,sha256=QBqdaooyRA3tUaDx7q_6mE97mTPRxUr3MsMNBdIvM7o,789
+pystormtracker/simple/__init__.py,sha256=p2Xc3gLfB3rQY3jQE3uK28qnBRxlFA8nV_OLItvdXtM,116
+pystormtracker/simple/detector.py,sha256=LJUprquT5AAsNBzQfpHdjw1N-46WmlfMRoqf8KUjKAY,10124
+pystormtracker/simple/linker.py,sha256=vvSJNFJTJbS0jgtwFZP6teewGIxHRHw-Eb9qIqKlQTA,3657
+pystormtracker-0.2.1.dist-info/METADATA,sha256=MonuLFZb2mW_5xRAS8TcAXgLcPZdvnFn5X1BlGZA2CU,6313
+pystormtracker-0.2.1.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+pystormtracker-0.2.1.dist-info/entry_points.txt,sha256=3X4UgACtC5CjzcEQ2ykR2j1rgctmvHm0PoSVDBBV5JA,66
+pystormtracker-0.2.1.dist-info/licenses/LICENSE,sha256=6X-vHoP9tzZOg2t88mmLa0kwgcS-MDPcmjHfj5nX7NU,2214
+pystormtracker-0.2.1.dist-info/RECORD,,

pystormtracker-0.2.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

pystormtracker-0.2.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+stormtracker = pystormtracker.stormtracker:main

pystormtracker-0.2.1.dist-info/licenses/LICENSE

@@ -0,0 +1,40 @@
+Copyright (c) 2015, University Corporation for Atmospheric Research (UCAR)
+Copyright (c) 2026, Albert M. W. Yau
+All rights reserved.
+
+Developed by: Application Scalability and Performance Group
+              University Corporation for Atmospheric Research -
+              National Center for Atmospheric Research
+              https://www.cisl.ucar.edu/
+
+Developed by: Albert M. W. Yau
+              https://github.com/mwyau/PyStormTracker
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the "Software"),
+to deal with 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:
+
+- Redistributions of source code must retain the above copyright notice,
+  this list of conditions and the following disclaimers.
+- Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimers in the documentation
+  and/or other materials provided with the distribution.
+- Neither the names of the Application Scalability and Performance (ASAP)
+  Group, UCAR, nor the names of its contributors may be used to endorse or
+  promote products derived from this Software without specific prior written
+  permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGE.