MOAAP Reference

Main Interface

moaap.main.moaap(Lon, Lat, Time, dT, Mask, *, config_file=None, **kw)

Parameters:

• Lon (array_like) – 2D array of longitude grid centers.

• Lat (array_like) – 2D array of latitude grid centers.

• Time (array_like of datetime) – 1D vector of datetimes for each time step.

• dT (int) – Temporal frequency of the data in hours.

• Mask (array_like) – 2D mask defining the analysis region.

Keyword Arguments:

• v850 (array_like or None, default=None) – 850 hPa zonal wind speed (m/s).

• u850 (array_like or None, default=None) – 850 hPa meridional wind speed (m/s).

• t850 (array_like or None, default=None) – 850 hPa air temperature (K).

• q850 (array_like or None, default=None) – 850 hPa mixing ratio (g/kg).

• slp (array_like or None, default=None) – Sea level pressure (Pa).

• ivte (array_like or None, default=None) – Zonal integrated vapor transport (kg m⁻¹ s⁻¹).

• ivtn (array_like or None, default=None) – Meridional integrated vapor transport (kg m⁻¹ s⁻¹).

• z500 (array_like or None, default=None) – Geopotential height at 500 hPa (gpm).

• v200 (array_like or None, default=None) – 200 hPa zonal wind speed (m/s).

• u200 (array_like or None, default=None) – 200 hPa meridional wind speed (m/s).

• pr (array_like or None, default=None) – Accumulated surface precipitation (mm per time step).

• tb (array_like or None, default=None) – Brightness temperature (K).

• DataName (str, default='') – Name of the common grid.

• OutputFolder (str, default='') – Path to the output directory.

Moisture streams:

• MinTimeMS (int, default=9) – Minimum lifetime of moisture stream features (h).

• MinAreaMS (float, default=100000) – Minimum area of moisture stream features (km²).

• MinMSthreshold (float, default=0.11) – Detection threshold for moisture streams (g·m/g·s).

• breakup_ms (str, default=’watershed’) – Method for moisture stream breakup.

• analyze_ms_history (bool, default=False) – If True, computes watershed merge/split history for moisture streams.

Cyclones & anticyclones:

• MinTimeCY (int, default=12) – Minimum lifetime of cyclones (h).

• MaxPresAnCY (float, default=-8) – Pressure anomaly threshold for cyclones (hPa).

• breakup_cy (str, default=’watershed’) – Method for cyclone breakup.

• MinTimeACY (int, default=12) – Minimum lifetime of anticyclones (h).

• MinPresAnACY (float, default=6) – Pressure anomaly threshold for anticyclones (hPa).

• analyze_psl_history (bool, default=False) – If True, computes watershed merge/split history for cyclones/anticyclones.

Frontal zones:

• MinAreaFR (float, default=50000) – Minimum area of frontal zones (km²).

• front_treshold (float, default=1) – Threshold for masking frontal zones.

Cloud tracking:

• SmoothSigmaC (float, default=0) – Gaussian σ for cloud‐shield smoothing.

• Cthreshold (float, default=241) – Brightness temperature threshold for ice‐cloud shields (K).

• MinTimeC (int, default=4) – Minimum lifetime of ice‐cloud shields (h).

• MinAreaC (float, default=40000) – Minimum area of ice‐cloud shields (km²).

• analyze_cloud_history (bool, default=False) – If True, computes watershed merge/split history for cloud objects.

Atmospheric rivers (AR):

• IVTtrheshold (float, default=500) – Integrated vapor transport threshold for AR detection (kg m⁻¹ s⁻¹).

• MinTimeIVT (int, default=12) – Minimum lifetime of ARs (h).

• breakup_ivt (str, default=’watershed’) – Method for AR breakup.

• AR_MinLen (float, default=2000) – Minimum length of an AR (km).

• AR_Lat (float, default=20) – Minimum centroid latitude for ARs (degrees N).

• AR_width_lenght_ratio (float, default=2) – Minimum length‐to‐width ratio for ARs.

• analyze_ivt_history (bool, default=False) – If True, computes watershed merge/split history for ARs.

Tropical cyclone detection:

• TC_Pmin (float, default=995) – Minimum central pressure for TC detection (hPa).

• TC_lat_genesis (float, default=35) – Maximum latitude for TC genesis (degrees).

• TC_lat_max (float, default=60) – Maximum latitude for TC existence (degrees).

• TC_deltaT_core (float, default=0) – Minimum core‐to‐environment temperature difference (K).

• TC_T850min (float, default=285) – Minimum core temperature at 850 hPa for TCs (K).

Mesoscale convective systems (MCS):

• MCS_Minsize (float, default=5000) – Minimum precipitation area size for MCS (km²).

• MCS_minPR (float, default=15) – Precipitation threshold for MCS detection (mm h⁻¹).

• CL_MaxT (float, default=215) – Maximum brightness temperature in ice shield for MCS (K).

• CL_Area (float, default=40000) – Minimum cloud area for MCS detection (km²).

• MCS_minTime (int, default=4) – Minimum lifetime of MCS (h).

• analyze_mcs_history (bool, default=False) – Whether to analyze the history of MCS objects.

Jet streams & tropical waves:

• js_min_anomaly (float, default=37) – Minimum jet‐stream anomaly (m/s).

• MinTimeJS (int, default=24) – Minimum lifetime of jet streams (h).

• breakup_jet (str, default=’watershed’) – Method for jet‐stream breakup.

• tropwave_minTime (int, default=48) – Minimum lifetime of tropical waves (h).

• breakup_mcs (str, default=’watershed’) – Method for MCS breakup.

• analyze_jet_history (bool, default=False) – If True, computes watershed merge/split history for jet streams.

• analyze_twave_history (bool, default=False) – If True, computes watershed merge/split history for tropical waves.

500 hPa cyclones/anticyclones:

• z500_low_anom (float, default=-80) – Minimum anomaly for 500 hPa cyclones (m).

• z500_high_anom (float, default=70) – Minimum anomaly for 500 hPa anticyclones (m).

• breakup_zcy (str, default=’watershed’) – Method for 500 hPa cyclone/anticyclone breakup.

• analyze_z500_history (bool, default=False) – If True, computes watershed merge/split history for 500 hPa cyclones/anticyclones.

Equatorial waves:

• er_th (float, default=0.05) – Threshold for equatorial Rossby waves.

• mrg_th (float, default=0.05) – Threshold for mixed Rossby‐gravity waves.

• igw_th (float, default=0.20) – Threshold for inertia–gravity waves.

• kel_th (float, default=0.10) – Threshold for Kelvin waves.

• eig0_th (float, default=0.10) – Threshold for n≥1 inertia–gravity waves.

• breakup_tw (str, default=’watershed’) – Method for equatorial wave breakup.

Returns:

A dictionary containing detected features grouped by type (e.g., ‘precip’, ‘moisture’, ‘cyclones’, etc.).

Return type:

dict

Utils

moaap.utils.data_proc.fill_small_gaps(data, gap_threshold=12)

Replace gaps (sequences of zeros) with ones if the gap length is less than the specified gap_threshold. Only gaps that are flanked by ones are filled.

Parameters:

datalist or np.ndarray

Time series of zeros and ones.

gap_thresholdint, optional

Maximum number of zeros allowed in a gap to be filled with ones. (Default value is 12)

Returns:

np.ndarray

The modified time series with small gaps filled.

moaap.utils.data_proc.interpolate_temporal(arr)

Fill missing (np.nan) values along axis-0 (time) by linear interpolation.

Parameters:

arr (ndarray, shape (ntime, nlat, nlon)) – Input brightness‐temperature (or any) data, with np.nan marking missing.

Returns:

result – Same as arr but with NaNs replaced via 1D linear interpolation in time. If an entire time series is NaN, it remains NaN. Leading/trailing NaNs become constant at the first/last valid value.

Return type:

ndarray, shape (ntime, nlat, nlon), dtype float64

moaap.utils.data_proc.smooth_uniform(data, t_smoot, xy_smooth)

Applies a uniform (box) smoothing filter in time and space, handling NaNs by separating valid data from masks.

Parameters:

• data (np.ndarray) – Input array [time, lat, lon].

• t_smoot (int) – Size of the smoothing window in the time dimension.

• xy_smooth (int) – Size of the smoothing window in spatial dimensions.

Returns:

smooth_data – The smoothed data array.

Return type:

np.ndarray

moaap.utils.data_proc.temporal_tukey_window(nt, alpha=0.1)

Create a Tukey window for temporal tapering.

Parameters:

• nt (int) – number of time steps

• alpha (float) – fraction of the window length to taper (e.g. 0.1 → 10% on each end)

Returns:

w – Tukey window of length nt

Return type:

np.ndarray

moaap.utils.data_proc.tukey_latitude_mask(lat_matrix: ndarray, lat_start: float, lat_stop: float) → ndarray

Build a latitude-dependent Tukey taper mask.

Parameters:

• lat_matrix (np.ndarray) – 2D array of center-point latitudes (degrees), shape (ny, nx).

• lat_start (float) – Latitude (in degrees) where the taper begins (|lat| <= lat_start => weight=1).

• lat_stop (float) – Latitude (in degrees) where the taper ends (|lat| >= lat_stop => weight=0).

Returns:

mask – 2D taper mask of same shape as lat_matrix, with values in [0,1].

Return type:

np.ndarray

moaap.utils.grid.DistanceCoord(Lo1, La1, Lo2, La2)

Calculate the great circle distance between two points on the earth (specified in decimal degrees)

Parameters:

• Lo1 (float) – Longitude of point 1.

• La1 (float) – Latitude of point 1.

• Lo2 (float) – Longitude of point 2.

• La2 (float) – Latitude of point 2.

Returns:

distance – Distance between point 1 and point 2 in kilometers.

Return type:

float

moaap.utils.grid.calc_grid_distance_area(lon, lat)

Calculates grid cell dimensions and areas using the Haversine formula. Approximates distances for a 2D grid of coordinates.

Parameters:

• lon (np.ndarray) – 2D array of longitudes [lat, lon].

• lat (np.ndarray) – 2D array of latitudes [lat, lon].

Returns:

• dx (np.ndarray) – Zonal grid spacing (m).

• dy (np.ndarray) – Meridional grid spacing (m).

• area (np.ndarray) – Area of each grid cell (m^2).

• grid_distance (float) – Mean grid spacing over the domain (m).

moaap.utils.grid.haversine(lon1, lat1, lon2, lat2)

Calculate the great circle distance between two points on the earth.

Parameters:

• lon1 (float or np.ndarray) – Coordinates of the first point(s) in degrees.

• lat1 (float or np.ndarray) – Coordinates of the first point(s) in degrees.

• lon2 (float or np.ndarray) – Coordinates of the second point(s) in degrees.

• lat2 (float or np.ndarray) – Coordinates of the second point(s) in degrees.

Returns:

km – Distance in kilometers (assuming Earth radius of 6367 km).

Return type:

float or np.ndarray

moaap.utils.grid.radialdistance(lat1, lon1, lat2, lon2)

Calculate the great circle distance between two points on the earth (specified in decimal degrees).

Parameters:

• lat1 (float) – Coordinates of the first point in degrees.

• lon1 (float) – Coordinates of the first point in degrees.

• lat2 (float) – Coordinates of the second point in degrees.

• lon2 (float) – Coordinates of the second point in degrees.

Returns:

distance – Distance in kilometers.

Return type:

float

moaap.utils.object_props.BreakupObjects(DATA, min_tsteps, dT, obj_history=False)

Splits long-living objects that may be artificially merged (e.g., distinct storms merging for one timestep). It analyzes the 2D connectivity over time and keeps the largest consistent overlap.

Parameters:

• DATA (np.ndarray) – 3D matrix [time, lat, lon] containing labeled objects.

• min_tsteps (int) – Minimum lifetime (in timesteps) required to keep an object.

• dT (int) – Time resolution of the data in hours.

• obj_history (bool, optional) – If True, calculates how objects start and end (merges/splits).

Returns:

• DATA_fin (np.ndarray) – The re-labeled 3D object array.

• object_split (dict or None) – Dictionary containing splitting/merging history if obj_history is True.

moaap.utils.object_props.ConnectLon_on_timestep(object_indices)

This function connects objects over the date line on a time-step by time-step basis, which makes it different from the ConnectLon function. This function is needed when long-living objects are first split into smaller objects using the BreakupObjects function.

Parameters:

object_indices (np.ndarray) – Array of object indices from ndimage.find_objects

Returns:

object_indices – Updated array of object indices with connected objects across the date line.

Return type:

np.ndarray

moaap.utils.object_props.calc_object_characteristics(var_objects, var_data, filename_out, times, Lat, Lon, grid_spacing, grid_cell_area, min_tsteps=1, history=None)

Calculates comprehensive statistics for tracked objects, including size, intensity, velocity, and trajectory.

Parameters:

• var_objects (np.ndarray) – 3D labeled object array.

• var_data (np.ndarray) – Original data field used for detection (e.g., precipitation, pressure).

• filename_out (str) – Path to save the resulting dictionary as a pickle file.

• times (np.ndarray) – Array of datetime objects corresponding to the time axis.

• Lat (np.ndarray) – Latitude and Longitude grids.

• Lon (np.ndarray) – Latitude and Longitude grids.

• grid_spacing (float) – Average grid spacing (m).

• grid_cell_area (np.ndarray) – Area of grid cells.

• min_tsteps (int, optional) – Minimum timesteps an object must exist to be processed.

• history (dict, optional) – Dictionary containing object history information from a previous call of analyze_watershed_history.

Returns:

objects_charac – Dictionary where keys are object IDs and values are dictionaries containing: ‘mass_center_loc’, ‘speed’, ‘tot’, ‘min’, ‘max’, ‘mean’, ‘size’, ‘times’, ‘track’.

Return type:

dict

moaap.utils.object_props.clean_up_objects(DATA, dT, min_tsteps=0, obj_splitmerge=None)

Function to remove objects that are too short lived and to numerrate the object from 1…N

Parameters:

• DATA (np.ndarray) – Labeled object array [time, lat, lon].

• dT (int) – Time step (hours).

• min_tsteps (int) – Minimum lifetime of objects to keep (hours).

• obj_splitmerge (dict, optional) – Dictionary tracking object splits/merges. Default is None.

Returns:

• objectsTMP (np.ndarray) – Cleaned labeled object array.

• obj_splitmerge_clean (dict) – Updated split/merge history dictionary.

moaap.utils.object_props.is_land(x, y)

moaap.utils.object_props.minimum_bounding_rectangle(points)

Find the smallest bounding rectangle for a set of points. Returns a set of points representing the corners of the bounding box.

Parameters:

points – an nx2 matrix of coordinates

Rval:

an nx2 matrix of coordinates

class moaap.utils.profiling.SectionTimer(name, results_dict)

Bases: object

moaap.utils.profiling.profile_sections(func)

Decorator to profile execution time of code sections within a function.

Usage:

@profile_sections

def my_function(…, _timer=None):

with _timer(“section1”):

…

moaap.utils.profiling.timer(start, end)

Prints elapsed time in hh:mm:ss.ss format.

Parameters:

• start (float) – Start time in seconds.

• end (float) – End time in seconds.

Return type:

None (output via print)

class moaap.utils.segmentation.UnionFind

Bases: object

A Union-Find (Disjoint Set) data structure. Assumes each ‘label’ (int) is a unique object ID.

add(item: int)

find(item: int) → int

union(item1: int, item2: int)

moaap.utils.segmentation.analyze_watershed_history(watershed_results, min_dist, object_type: str, histplot: bool = False)

Analyze the history of watershed objects over time. The output is a union of all objects which merged or split over time, along with a list of events (merges and splits) that occurred and the history array (dict of sets), where two labels are in one set if they are connected via merges/splits. This is done via Euler-timestepping and comparing the overlap of objects. This function also creates a plot of the history of all objects showing merges and splits of at most 40 objects (for better readability).

Parameters:

• watershed_results (np.ndarray) – 3D array of watershed labels over time, shape (T, H, W).

• min_dist (float) – Minimum distance threshold to consider two objects as related (for merges/splits).

• object_type (str) – Type of object being analyzed (e.g., “mcs”, “cloud”).

• histplot (bolean) – Switch to turn on plotting of object history

Returns:

• union_array (Dict[int, int]) – Mapping of each label to its root label in the union-find structure.

• events (List[Dict[str, Any]]) – List of merge and split events with details.

• histories (Dict[int, Set[int]]) – Dictionary mapping root labels to sets of all connected labels.

moaap.utils.segmentation.build_object_history_dict(labels, centers, events, uf, histories, object_type=None, out_dir='outputs', save=True)

Build per-object history records (lifetime + interactions) from watershed tracking outputs.

Parameters:

• labels (array-like of int) – All nonzero object labels.

• centers (dict) – centers[label][t] -> (y, x) or similar. Used only to infer lifetimes.

• events (list of dict) – Each event dict must have keys: - ‘type’ in {‘merge’,’split’} - ‘time’ (int) - ‘from_label’ (int) - ‘to_label’ (int) - ‘distance’ (float)

• uf (UnionFind) – Must implement uf.find(label) and have uf.parent mapping.

• histories (dict[int, set[int]]) – Root -> set of labels connected by merges/splits.

Returns:

object_data – object_data[label] is the record for that object label.

Return type:

dict[int, dict]

moaap.utils.segmentation.connect_3d_objects(labels, min_tsteps, dT)

Links 2D labeled slices into 3D objects based on maximum spatial overlap between consecutive time steps.

Parameters:

• labels (np.ndarray) – 3D array where each [t, :, :] slice contains independent 2D labels.

• min_tsteps (int) – Minimum duration to keep an object.

• dT (int) – Time step.

Returns:

objects_watershed – 3D array with consistent object IDs tracked over time.

Return type:

np.ndarray

moaap.utils.segmentation.label_peaks_over_time_3d(coords, max_dist=5)

Labels peaks in 3D coordinates over time based on spatial proximity.

Parameters:

• coords – np.ndarray of shape (N_peaks, 3), each row is [t, y, x]

• max_dist – maximum allowed distance to consider peaks as the same object (in grid units)

Returns:

np.ndarray of shape (N_peaks,), integer labels for each peak over time

Return type:

labels

moaap.utils.segmentation.watershed_2d_overlap(data, object_threshold, max_treshold, min_dist, dT, mintime=24, connectLon=0, extend_size_ratio=0.25, erosion_disk=3.5)

This function performs watershedding on 2D anomaly fields over time and connects the resulting 2D features into 3D objects based on maximum overlap. This function uses spatially reduced watersheds from the previous time step as seed for the current time step, which improves temporal consistency of features.

Parameters:

• data (np.ndarray) – 3D array of data for watershedding [time, lat, lon].

• object_threshold (float) – Threshold to create binary object mask.

• max_treshold (float) – Threshold for identifying maximum points for spreading.

• min_dist (int) – Minimum distance (in grid cells) between maximum points.

• dT (int) – Time interval in hours.

• mintime (int, optional) – Minimum time an object has to exist in dT. Default is 24.

• connectLon (int, optional) – Whether to track features over the date line (1 for yes, 0 for no). Default is 0.

• extend_size_ratio (float, optional) – If connectLon = 1, this sets the ratio of the zonal domain added to the watershedding. This has to be big for large objects (e.g., ARs) and can be smaller for e.g., MCSs. Default is 0.25.

• erosion_disk (float, optional) – Disk size for erosion of previous timestep mask to improve temporal connection of features. Default is 3.5.

moaap.utils.segmentation.watershed_3d_overlap(data: ndarray, object_threshold: float, max_treshold: float, min_dist: int, dT: int, mintime: int = 24, connectLon: int = 0, extend_size_ratio: float = 0.25) → ndarray

Perform 3D watershedding on the input data with temporal consistency.

Parameters:

• data (np.ndarray) – 3D matrix with data for watershedding

• object_threshold (float) – Float to create binary object mast

• max_treshold (float) – Value for identifying max. points for spreading

• min_dist (int) – Minimum distance (in grid cells) between maximum points

• dT (int) – Time interval in hours

• mintime (int, optional) – Minimum time an object has to exist in dT, by default 24

• connectLon (int, optional) – Do we have to track features over the date line?, by default 0

• extend_size_ratio (float, optional) – If connectLon = 1 this key is setting the ratio of the zonal domain added to the watershedding. This has to be big for large objects (e.g., ARs) and can be smaller for e.g., MCSs, by default 0.25

Returns:

3D matrix with watershed labels

Return type:

np.ndarray

moaap.utils.segmentation.watershed_3d_overlap_parallel(data, object_threshold, max_treshold, min_dist, dT, mintime=24, connectLon=0, extend_size_ratio=0.25, n_chunks_lat=1, n_chunks_lon=1, overlap_cells=None, mp_method='auto')

Parallel version of watershed_3d_overlap using domain decomposition.

Parameters:

• data (np.ndarray) – 3D matrix with data for watershedding

• object_threshold (float) – Float to create binary object mask

• max_treshold (float) – Value for identifying max. points for spreading

• min_dist (int) – Minimum distance (in grid cells) between maximum points

• dT (int) – Time interval in hours

• mintime (int, optional) – Minimum time an object has to exist in dT, by default 24

• connectLon (int, optional) – Do we have to track features over the date line?, by default 0

• extend_size_ratio (float, optional) – If connectLon = 1 this key is setting the ratio of the zonal domain added to the watershedding. This has to be big for large objects (e.g., ARs) and can be smaller for e.g., MCSs, by default 0.25

• n_chunks_lat (int, default=None) – Number of chunks to split latitude dimension, if None, auto-detects based on CPU count

• n_chunks_lon (int, default=None) – Number of chunks to split longitude dimension

• overlap_cells (int, optional) – Number of overlapping cells between chunks. If None, uses min_dist * 2

• mp_method (str, optional) – Multiprocessing method: ‘fork’, ‘spawn’, or ‘auto’ (default). ‘auto’ chooses based on data size and system memory.

Returns:

3D matrix with watershed labels

Return type:

np.ndarray

Trackers

moaap.trackers.atmospheric_rivers.ar_850hpa_tracking(VapTrans, MinMSthreshold, MinTimeMS, MinAreaMS, Area, dT, connectLon, Gridspacing, breakup='watershed', analyze_ms_history=False)

Tracks Moisture Streams (MS) based on 850 hPa moisture flux.

Parameters:

• VapTrans (np.ndarray) – Moisture flux magnitude [g/kg * m/s].

• MinMSthreshold (float) – Threshold for detection.

• MinTimeMS (int) – Minimum lifetime (hours).

• MinAreaMS (float) – Minimum area (km^2).

• Area (np.ndarray) – Grid cell area array.

• dT (int) – Time step (hours).

• connectLon (int) – 1 to connect across date line.

• Gridspacing (float) – Grid spacing (m).

• breakup (str, optional) – Method for object separation. Options: ‘breakup’ or ‘watershed’. Default is ‘watershed’.

• analyze_ms_history (bool, optional) – If True, computes watershed merge/split history.

Returns:

MS_objects – Labeled moisture stream objects.

Return type:

np.ndarray

moaap.trackers.atmospheric_rivers.ar_check(objects_mask, AR_Lat, AR_width_lenght_ratio, AR_MinLen, Lon, Lat)

Filters potential AR objects based on geometric criteria (Centroid latitude, Length, and Length/Width ratio).

Parameters:

• objects_mask (np.ndarray) – Labeled AR candidate objects.

• AR_Lat (float) – Minimum latitude for the object centroid (to filter tropical moisture).

• AR_width_lenght_ratio (float) – Minimum length-to-width ratio (ARs must be elongated).

• AR_MinLen (float) – Minimum length of the object in km.

• Lon (np.ndarray) – Longitude and Latitude grids.

• Lat (np.ndarray) – Longitude and Latitude grids.

Returns:

AR_obj – Filtered array containing only valid AR objects.

Return type:

np.ndarray

moaap.trackers.atmospheric_rivers.ar_ivt_tracking(IVT, IVTtrheshold, MinTimeIVT, dT, Gridspacing, connectLon, breakup='watershed', analyze_ivt_history=False)

Tracks Atmospheric Rivers (ARs) based on Integrated Vapor Transport (IVT).

Parameters:

• IVT (np.ndarray) – Total IVT magnitude [time, lat, lon].

• IVTtrheshold (float) – Threshold to define AR candidates.

• MinTimeIVT (int) – Minimum duration an AR object must exist (hours).

• dT (int) – Data timestep (hours).

• Gridspacing (float) – Grid spacing in meters.

• connectLon (int) – 1 to connect objects across the date line, 0 otherwise.

• breakup (str, optional) – Method to handle merging objects (‘breakup’ or ‘watershed’). Default is ‘watershed’.

• analyze_ivt_history (bool, optional) – If True, computes watershed merge/split history. Default is False.

Returns:

IVT_objects – Labeled array of tracked IVT objects.

Return type:

np.ndarray

moaap.trackers.clouds.cloud_tracking(tb, pr, connectLon, Gridspacing, dT, tb_threshold=241, tb_overshoot=235, erosion_disk=1.5, min_dist=8, analyze_cloud_history=False)

Tracks clouds from hourly or sub-hourly brightness temperature data. Calculates cloud statistics, including their precipitation (pr) properties if pr is provided.

Parameters:

• (float) (Gridspacing)

• (float)

• (bol) (connectLon)

• (float)

• (int) (dT)

• (float (erosion_disk)

• optional) (If True, computes watershed merge/split history. Default is False.)

• (float

• optional)

• (float

• optional)

• (int (min_dist)

• optional)

• (bool (analyze_cloud_history)

• optional)

Returns:

cloud_objects (np.ndarray)

Return type:

labeled cloud objects of dimension [time,lat,lon]

moaap.trackers.clouds.mcs_tb_tracking(tb, pr, SmoothSigmaC, Pthreshold, CL_Area, CL_MaxT, Cthreshold, MinAreaC, MinTimeC, MCS_minPR, MCS_minTime, MCS_Minsize, dT, Area, connectLon, Gridspacing, breakup='watershed', analyze_mcs_history=False)

Tracks Mesoscale Convective Systems (MCS) using Brightness Temperature (Tb). Verifies candidates using precipitation criteria.

Parameters:

• tb (np.ndarray) – Brightness temperature [K].

• pr (np.ndarray) – Precipitation [mm/h].

• SmoothSigmaC (float) – Smoothing factor for Tb.

• Pthreshold (float) – Precipitation threshold.

• CL_Area (float) – Cloud shield area and max temp thresholds.

• CL_MaxT (float) – Cloud shield area and max temp thresholds.

• Cthreshold (float) – Tb threshold for initial cloud detection.

• MinAreaC (float) – Minimum cloud area for initial detection.

• MinTimeC (int) – Minimum cloud duration.

• MCS_minPR (float) – Minimum peak precipitation for MCS verification.

• MCS_minTime (int) – Minimum MCS duration.

• MCS_Minsize (float) – Minimum precipitation area for MCS verification.

• dT (int) – Data timestep (hours).

• Area (np.ndarray) – Grid cell area array.

• connectLon (int) – 1 to connect objects across date line.

• Gridspacing (float) – Grid spacing in meters.

• breakup (str) – Method to handle merging objects (‘breakup’ or ‘watershed’).

• analyze_mcs_history (bool) – If True, computes watershed merge/split history.

Returns:

• MCS_objects_Tb (np.ndarray) – Labeled MCS objects based on Tb.

• C_objects (np.ndarray) – Labeled cloud objects (all clouds, not just MCS).

moaap.trackers.cyclones.col_identification(cy_z500_objects, z500, u200, Frontal_Diagnostic, MinTimeC, dx, dy, Lon, Lat)

Identifies Cut-Off Lows (COLs) from tracked upper-level cyclones. Checks for isolation (Z500 gradient), flow reversal (poleward easterlies), and frontal separation.

Parameters:

• cy_z500_objects (np.ndarray) – Labeled 500hPa cyclone objects.

• z500 (np.ndarray) – Geopotential height at 500hPa.

• u200 (np.ndarray) – Zonal wind at 200hPa.

• Frontal_Diagnostic (np.ndarray) – Frontal parameter field.

• MinTimeC (int) – Minimum lifetime required.

• dx (np.ndarray) – Grid spacing arrays.

• dy (np.ndarray) – Grid spacing arrays.

Returns:

col_obj – Labeled Cut-Off Low objects.

Return type:

np.ndarray

moaap.trackers.cyclones.cy_acy_psl_tracking(slp, MaxPresAnCY, MinTimeCY, MinPresAnACY, MinTimeACY, dT, Gridspacing, connectLon, breakup='watershed', analyze_psl_history=False)

Tracks Cyclones (CY) and Anticyclones (ACY) based on Sea Level Pressure (SLP) anomalies.

Parameters:

• slp (np.ndarray) – Sea Level Pressure data [Pa].

• MaxPresAnCY (float) – Maximum anomaly threshold for Cyclones.

• MinTimeCY (int) – Minimum lifetime for Cyclones (hours).

• MinPresAnACY (float) – Minimum anomaly threshold for Anticyclones.

• MinTimeACY (int) – Minimum lifetime for Anticyclones (hours).

• dT (int) – Time step (hours).

• Gridspacing (float) – Average grid spacing (m).

• connectLon (int) – 1 to connect across date line.

• breakup (str) – Method for object separation (‘breakup’ or ‘watershed’).

• analyze_psl_history (bool, optional) – If True, computes watershed merge/split history. Default is False.

Returns:

• CY_objects (np.ndarray) – Labeled Cyclone objects.

• ACY_objects (np.ndarray) – Labeled Anticyclone objects.

moaap.trackers.cyclones.cy_acy_z500_tracking(z500, MinTimeCY, dT, Gridspacing, connectLon, z500_low_anom=-80, z500_high_anom=70, breakup='breakup', analyze_z500_history=False)

Tracks mid-tropospheric cyclones and anticyclones based on Z500 anomalies.

Parameters:

• z500 (np.ndarray) – Geopotential height at 500 hPa [m or gpm].

• MinTimeCY (int) – Minimum lifetime (hours).

• dT (int) – Time step (hours).

• Gridspacing (float) – Grid spacing (m).

• connectLon (int) – 1 to connect across date line.

• z500_low_anom (float) – Anomaly threshold for cyclones (e.g., -80 m).

• z500_high_anom (float) – Anomaly threshold for anticyclones (e.g., +70 m).

• breakup (str) – Method for object separation.

Returns:

• cy_z500_objects (np.ndarray) – Labeled Z500 cyclone objects.

• acy_z500_objects (np.ndarray) – Labeled Z500 anticyclone objects.

moaap.trackers.fronts.frontal_identification(Frontal_Diagnostic, front_treshold, MinAreaFR, Area)

Identifies frontal zones based on a thermal frontal parameter.

Parameters:

• Frontal_Diagnostic (np.ndarray) – Calculated frontal diagnostic field (F*).

• front_treshold (float) – Threshold value to identify fronts.

• MinAreaFR (float) – Minimum area required for a frontal zone (km^2).

• Area (np.ndarray) – Grid cell area array.

Returns:

FR_objects – Labeled frontal zone objects.

Return type:

np.ndarray

moaap.trackers.jets.jetstream_tracking(uv200, js_min_anomaly, MinTimeJS, dT, Gridspacing, connectLon, breakup='watershed', analyze_jet_history=False)

Identifies and tracks Jet Stream objects based on 200hPa wind speed anomalies.

Parameters:

• uv200 (np.ndarray) – Wind speed at 200 hPa [m/s].

• js_min_anomaly (float) – Minimum wind speed anomaly to define a jet object.

• MinTimeJS (int) – Minimum lifetime (hours).

• dT (int) – Time step (hours).

• Gridspacing (float) – Grid spacing (m).

• connectLon (int) – 1 to connect across the date line.

• breakup (str, optional) – Method to split merged objects (‘breakup’ or ‘watershed’).

• analyze_jet_history (bool, optional) – If True, computes watershed merge/split history.

Returns:

• jet_objects (np.ndarray) – Labeled jet stream objects.

• object_split (dict) – History of object splitting/merging.

moaap.trackers.tropical_cyclones.tc_tracking(CY_objects, slp, t850, tb, uv850, uv200, Lon, Lat, TC_lat_genesis, TC_t_core)

Filters tracked surface cyclones to identify Tropical Cyclones (TCs). Checks for warm core, genesis latitude, low pressure, and wind structure.

Parameters:

• CY_objects (np.ndarray) – Labeled surface cyclone objects.

• slp (np.ndarray) – Sea Level Pressure.

• t850 (np.ndarray) – Temperature at 850hPa (for warm core check).

• tb (np.ndarray) – Brightness Temperature (for cloud shield check).

• uv850 (np.ndarray) – Wind speed magnitudes at 850hPa and 200hPa.

• uv200 (np.ndarray) – Wind speed magnitudes at 850hPa and 200hPa.

• TC_lat_genesis (float) – Maximum latitude for TC genesis.

• TC_t_core (float) – Minimum core temperature threshold.

Returns:

• TC_obj (np.ndarray) – Labeled Tropical Cyclone objects.

• TC_Tracks (dict) – Dictionary containing Lat/Lon tracks for each TC ID.

class moaap.trackers.waves.KFfilter(datain, spd, tim_taper=0.1)

Bases: object

class for wavenumber-frequency filtering for WK99 and WKH00

decompose_antisymm()

decompose attribute data to sym and antisym component.

Parameters:

None

eig0filter(fmin=None, fmax=0.55, kmin=0, kmax=15, hmin=12, hmax=50)

n>=0 eastward inertio gravirt wave filter.

Parameters:

• day ('fmin/fmax' -- unit is cycle per)

• westward ('kmin/kmax' -- zonal wave number. negative is) – eastward

• is (positive) – eastward

• depth ('hmin/hmax' -- equivalent)

Returns:

‘filterd’ – filtered data in the original data space

erfilter(fmin=None, fmax=None, kmin=-10, kmax=-1, hmin=8, hmax=90, n=1)

equatorial wave filter

Parameters:

• day ('fmin/fmax' -- unit is cycle per)

• number ('n' -- meridional mode)

• depth ('hmin/hmax' -- equivalent)

• number

Returns:

‘filterd’ – filtered data in the original data space

igfilter(fmin=None, fmax=None, kmin=-15, kmax=-1, hmin=12, hmax=90, n=1)

n>=1 inertio gravirt wave filter. default is n=1 WIG.

Parameters:

• day ('fmin/fmax' -- unit is cycle per)

• westward ('kmin/kmax' -- zonal wave number. negative is) – eastward

• is (positive) – eastward

• depth ('hmin/hmax' -- equivalent)

• number ('n' -- meridional mode)

Returns:

‘filterd’ – filtered data in the original data space

kelvinfilter(fmin=0.05, fmax=0.4, kmin=None, kmax=14, hmin=8, hmax=90)

kelvin wave filter

Parameters:

• day ('fmin/fmax' -- unit is cycle per)

• number ('kmin/kmax' -- zonal wave)

• depth ('hmin/hmax' --equivalent)

Returns:

‘filterd’ – filtered data in the original data space

kfmask(fmin=None, fmax=None, kmin=None, kmax=None)

return wavenumber-frequency mask for wavefilter method

Parameters:

• -- ('kmin/kmax')

• --

Returns:

‘mask’ – 2D boolean array (wavenumber, frequency).domain to be filterd

mrgfilter(fmin=None, fmax=None, kmin=-10, kmax=-1, hmin=8, hmax=90)

mixed Rossby gravity wave

Parameters:

• day ('fmin/fmax' -- unit is cycle per)

• westward ('kmin/kmax' -- zonal wave number. negative is) – eastward

• is (positive) – eastward

• depth ('hmin/hmax' -- equivalent)

Returns:

‘filterd’ – filtered data in the original data space

tdfilter(fmin=None, fmax=None, kmin=-20, kmax=-6)

KTH05 TD-type filter.

Parameters:

• day ('fmin/fmax' -- unit is cycle per)

• westward ('kmin/kmax' -- zonal wave number. negative is) – eastward

• is (positive) – eastward

Returns:

‘filterd’ – filtered data in the original data space

wavefilter(mask)

apply wavenumber-frequency filtering by original mask.

Parameters:

array ('mask' -- 2D boolean) – is False (True member to be zero)

Returns:

‘filterd’ – filtered data in the original data space

moaap.trackers.waves.track_tropwaves_tb(tb, Lat, connectLon, dT, Gridspacing, er_th=0.05, mrg_th=0.05, igw_th=0.2, kel_th=0.1, eig0_th=0.1, breakup='watershed', analyze_twave_history=False)

Identifies and tracks tropical waves using wavenumber-frequency filtering (Wheeler & Kiladis method) applied to precipitation data.

Parameters:

• pr (np.ndarray) – Precipitation data.

• Lat (np.ndarray) – Latitude grid.

• dT (int) – Time step (hours).

• er_th (float) – Amplitude thresholds for identifying Equatorial Rossby, Mixed Rossby Gravity, Inertia Gravity, Kelvin, and Eastward Inertia Gravity waves respectively.

• mrg_th (float) – Amplitude thresholds for identifying Equatorial Rossby, Mixed Rossby Gravity, Inertia Gravity, Kelvin, and Eastward Inertia Gravity waves respectively.

• igw_th (float) – Amplitude thresholds for identifying Equatorial Rossby, Mixed Rossby Gravity, Inertia Gravity, Kelvin, and Eastward Inertia Gravity waves respectively.

• kel_th (float) – Amplitude thresholds for identifying Equatorial Rossby, Mixed Rossby Gravity, Inertia Gravity, Kelvin, and Eastward Inertia Gravity waves respectively.

• eig0_th (float) – Amplitude thresholds for identifying Equatorial Rossby, Mixed Rossby Gravity, Inertia Gravity, Kelvin, and Eastward Inertia Gravity waves respectively.

• breakup (str) – Method to handle merging objects (‘breakup’ or ‘watershed’).

• analyze_twave_history (bool, optional) – If True, computes watershed merge/split history.

Returns:

mrg_objects, igw_objects, kelvin_objects, eig0_objects, er_objects – Labeled object arrays for each wave type.

Return type:

np.ndarray