Skip to content

Commit

Permalink
Merge branch 'RC_v1.5.x' into min_distance_3D_fix
Browse files Browse the repository at this point in the history
  • Loading branch information
@w-k-jones
w-k-jones authored Oct 14, 2024
2 parents 177904e + d9f2df8 commit 38f6eb9
Show file tree
Hide file tree
Showing 8 changed files with 576 additions and 192 deletions.
6 changes: 3 additions & 3 deletions doc/index.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,14 +10,14 @@ The software is set up in a modular way to include different algorithms for feat

Individual features are identified as either maxima or minima in a 2D or 3D time-varying field (see :doc:`feature_detection_overview`). An associated volume can then be determined using these features with a separate (or identical) time-varying 2D or 3D field and a threshold value (see :doc:`segmentation`). The identified objects are linked into consistent trajectories representing the cloud over its lifecycle in the tracking step. Analysis and visualization methods provide a convenient way to use and display the tracking results.

Version 1.2 of tobac and some example applications are described in a peer-reviewed article in Geoscientific Model Development as:
**Version 1.2 of tobac** and some example applications are described in a peer-reviewed article in Geoscientific Model Development as:

Heikenfeld, M., Marinescu, P. J., Christensen, M., Watson-Parris, D., Senf, F., van den Heever, S. C., and Stier, P.: tobac 1.2: towards a flexible framework for tracking and analysis of clouds in diverse datasets, Geosci. Model Dev., 12, 4551–4570, https://doi.org/10.5194/gmd-12-4551-2019, 2019.

Version 1.5 of tobac and the major enhancements that came with that version are currently under review in Geoscientific Model Development:
**Version 1.5 of tobac** and the major enhancements that came with that version are described in the following peer-reviewed article in Geoscientific Model Development:

Sokolowsky, G. A., Freeman, S. W., Jones, W. K., Kukulies, J., Senf, F., Marinescu, P. J., Heikenfeld, M., Brunner, K. N., Bruning, E. C., Collis, S. M., Jackson, R. C., Leung, G. R., Pfeifer, N., Raut, B. A., Saleeby, S. M., Stier, P., and van den Heever, S. C.: tobac v1.5: Introducing Fast 3D Tracking, Splits and Mergers, and Other Enhancements for Identifying and Analysing Meteorological Phenomena. Geoscientific Model Development, 17(13), 5309-5330. https://doi.org/10.5194/gmd-17-5309-2024, 2024.

Sokolowsky, G. A., Freeman, S. W., Jones, W. K., Kukulies, J., Senf, F., Marinescu, P. J., Heikenfeld, M., Brunner, K. N., Bruning, E. C., Collis, S. M., Jackson, R. C., Leung, G. R., Pfeifer, N., Raut, B. A., Saleeby, S. M., Stier, P., and van den Heever, S. C.: tobac v1.5: Introducing Fast 3D Tracking, Splits and Mergers, and Other Enhancements for Identifying and Analysing Meteorological Phenomena, EGUsphere [preprint], https://doi.org/10.5194/egusphere-2023-1722, 2023.

The project is currently being extended by several contributors to include additional workflows and algorithms using the same structure, syntax, and data formats.

Expand Down
4 changes: 4 additions & 0 deletions doc/publications.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,10 @@ Refereed Publications
:widths: 30
:class: wy-table-responsive

* - Sokolowsky, G. A., Freeman, S. W., Jones, W. K., Kukulies, J., Senf, F., Marinescu, P. J., Heikenfeld, M., Brunner, K. N., Bruning, E. C., Collis, S. M., Jackson, R. C., Leung, G. R., Pfeifer, N., Raut, B. A., Saleeby, S. M., Stier, P., and van den Heever, S. C.: tobac v1.5 (2024). Introducing Fast 3D Tracking, Splits and Mergers, and Other Enhancements for Identifying and Analysing Meteorological Phenomena. Geoscientific Model Development, 17(13), 5309-5330. https://doi.org/10.5194/gmd-17-5309-2024.

* - Heikenfeld, M., Marinescu, P. J., Christensen, M., Watson-Parris, D., Senf, F., van den Heever, S. C., and Stier, P. (2019). tobac 1.2: towards a flexible framework for tracking and analysis of clouds in diverse datasets, Geosci. Model Dev., 12, 4551–4570, https://doi.org/10.5194/gmd-12-4551-2019

* - Bukowski, J., & van den Heever, S. C. (2021). Direct radiative effects in haboobs. *Journal of Geophysical Research: Atmospheres*, 126(21), e2021JD034814, doi:10.1029/2021JD034814.

* - Bukowski, J. (2021). Mineral Dust Lofting and Interactions with Cold Pools (Doctoral dissertation, Colorado State University).
Expand Down
38 changes: 26 additions & 12 deletions tobac/feature_detection.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -627,9 +627,9 @@ def feature_detection_threshold(
# find the updated label, and overwrite all of label_ind indices with
# updated label
labels_2_alt = labels_2[label_z, y_val_alt, x_val_alt]
labels_2[
label_locs_v, label_locs_h1, label_locs_h2
] = labels_2_alt
labels_2[label_locs_v, label_locs_h1, label_locs_h2] = (
labels_2_alt
)
skip_list = np.append(skip_list, label_ind)
break

Expand Down Expand Up @@ -673,9 +673,9 @@ def feature_detection_threshold(
# find the updated label, and overwrite all of label_ind indices with
# updated label
labels_2_alt = labels_2[label_z, y_val_alt, label_x]
labels_2[
label_locs_v, label_locs_h1, label_locs_h2
] = labels_2_alt
labels_2[label_locs_v, label_locs_h1, label_locs_h2] = (
labels_2_alt
)
new_label_ind = labels_2_alt
skip_list = np.append(skip_list, label_ind)

Expand Down Expand Up @@ -717,9 +717,9 @@ def feature_detection_threshold(
# find the updated label, and overwrite all of label_ind indices with
# updated label
labels_2_alt = labels_2[label_z, label_y, x_val_alt]
labels_2[
label_locs_v, label_locs_h1, label_locs_h2
] = labels_2_alt
labels_2[label_locs_v, label_locs_h1, label_locs_h2] = (
labels_2_alt
)
new_label_ind = labels_2_alt
skip_list = np.append(skip_list, label_ind)

Expand Down Expand Up @@ -912,6 +912,7 @@ def feature_detection_multithreshold_timestep(
wavelength_filtering: tuple[float] = None,
strict_thresholding: bool = False,
statistic: Union[dict[str, Union[Callable, tuple[Callable, dict]]], None] = None,
statistics_unsmoothed: bool = False,
) -> pd.DataFrame:
"""Find features in each timestep.
Expand Down Expand Up @@ -984,6 +985,9 @@ def feature_detection_multithreshold_timestep(
Default is None. Optional parameter to calculate bulk statistics within feature detection.
Dictionary with callable function(s) to apply over the region of each detected feature and the name of the statistics to appear in the feature ou tput dataframe. The functions should be the values and the names of the metric the keys (e.g. {'mean': np.mean})
statistics_unsmoothed: bool, optional
Default is False. If True, calculate the statistics on the raw data instead of the smoothed input data.
Returns
-------
features_threshold : pandas DataFrame
Expand All @@ -1005,6 +1009,14 @@ def feature_detection_multithreshold_timestep(
# get actual numpy array and make a copy so as not to change the data in the iris cube
track_data = data_i.core_data().copy()

# keep a copy of the unsmoothed data (that can be used for calculating stats)
if statistics_unsmoothed:
if not statistic:
raise ValueError(
"Please provide the input parameter statistic to determine what statistics to calculate."
)


track_data = gaussian_filter(
track_data, sigma=sigma_threshold
) # smooth data slightly to create rounded, continuous field
Expand Down Expand Up @@ -1159,6 +1171,7 @@ def feature_detection_multithreshold(
dz: Union[float, None] = None,
strict_thresholding: bool = False,
statistic: Union[dict[str, Union[Callable, tuple[Callable, dict]]], None] = None,
statistics_unsmoothed: bool = False,
) -> pd.DataFrame:
"""Perform feature detection based on contiguous regions.
Expand Down Expand Up @@ -1374,6 +1387,7 @@ def feature_detection_multithreshold(
wavelength_filtering=wavelength_filtering,
strict_thresholding=strict_thresholding,
statistic=statistic,
statistics_unsmoothed=statistics_unsmoothed,
)

list_features_timesteps.append(features_thresholds)
Expand Down Expand Up @@ -1481,7 +1495,7 @@ def filter_min_distance(
target: {'maximum', 'minimum'}, optional
Flag to determine if tracking is targeting minima or maxima in
the data. Default is 'maximum'.
PBC_flag : str('none', 'hdim_1', 'hdim_2', 'both')
PBC_flag : str('none', 'hdim_1', 'hdim_2', 'both'), optional
Sets whether to use periodic boundaries, and if so in which directions.
'none' means that we do not have periodic boundaries
'hdim_1' means that we are periodic along hdim1
Expand Down Expand Up @@ -1553,8 +1567,8 @@ def filter_min_distance(
feature_locations = features[
[z_coordinate_name, y_coordinate_name, x_coordinate_name]
].to_numpy()
feature_locations[0] *= dz
feature_locations[1:] *= dxy
feature_locations[:, 0] *= dz
feature_locations[:, 1:] *= dxy
else:
feature_locations = (
features[[y_coordinate_name, x_coordinate_name]].to_numpy() * dxy
Expand Down
Loading

0 comments on commit 38f6eb9

Please sign in to comment.