tobac 1.6.3__tar.gz

tobac-1.6.3/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2019, climate-processes
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+
+* Neither the name of the copyright holder 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.

tobac-1.6.3/PKG-INFO

@@ -0,0 +1,154 @@
+Metadata-Version: 2.4
+Name: tobac
+Version: 1.6.3
+Summary: A package for identifying and tracking atmospheric phenomena
+Author-email: Max Heikenfeld <max.heikenfeld@physics.ox.ac.uk>, William Jones <william.jones@physics.ox.ac.uk>, Fabian Senf <senf@tropos.de>, Sean Freeman <sean.freeman@uah.edu>, Julia Kukulies <kukulies@ucar.edu>, Kelcy Brunner <Kelcy.Brunner@ttu.edu>, Sven Starzer <sven.starzer@proton.me>
+License: BSD-3-Clause
+Project-URL: Homepage, http://github.com/tobac-project/tobac
+Project-URL: Documentation, http://tobac.io
+Project-URL: Issues, http://github.com/tobac-project/tobac/issues
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
+Requires-Python: <3.14,>=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: scipy
+Requires-Dist: scikit-image
+Requires-Dist: scikit-learn
+Requires-Dist: pandas<3
+Requires-Dist: matplotlib
+Requires-Dist: scitools-iris
+Requires-Dist: xarray
+Requires-Dist: cartopy
+Requires-Dist: trackpy
+Requires-Dist: typing_extensions
+Provides-Extra: dev
+Requires-Dist: pre-commit; extra == "dev"
+Requires-Dist: black; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: nbconvert; extra == "dev"
+Provides-Extra: examples
+Requires-Dist: jupyter; extra == "examples"
+Requires-Dist: notebook; extra == "examples"
+Requires-Dist: pytables; extra == "examples"
+Requires-Dist: s3fs; extra == "examples"
+Requires-Dist: arm_pyart; extra == "examples"
+Requires-Dist: seaborn; extra == "examples"
+Requires-Dist: h5netcdf; extra == "examples"
+Requires-Dist: rioxarray; extra == "examples"
+Requires-Dist: numba; extra == "examples"
+Requires-Dist: dask; extra == "examples"
+Requires-Dist: intake==0.7.0; extra == "examples"
+Requires-Dist: intake-xarray==0.7.0; extra == "examples"
+Requires-Dist: healpix; extra == "examples"
+Requires-Dist: easygems; extra == "examples"
+Provides-Extra: all
+Requires-Dist: pre-commit; extra == "all"
+Requires-Dist: black; extra == "all"
+Requires-Dist: pytest; extra == "all"
+Requires-Dist: nbconvert; extra == "all"
+Requires-Dist: jupyter; extra == "all"
+Requires-Dist: notebook; extra == "all"
+Requires-Dist: pytables; extra == "all"
+Requires-Dist: s3fs; extra == "all"
+Requires-Dist: arm_pyart; extra == "all"
+Requires-Dist: seaborn; extra == "all"
+Requires-Dist: h5netcdf; extra == "all"
+Requires-Dist: rioxarray; extra == "all"
+Requires-Dist: numba; extra == "all"
+Requires-Dist: dask; extra == "all"
+Requires-Dist: intake==0.7.0; extra == "all"
+Requires-Dist: intake-xarray==0.7.0; extra == "all"
+Requires-Dist: healpix; extra == "all"
+Requires-Dist: easygems==0.1.2; extra == "all"
+Dynamic: license-file
+
+# tobac - Tracking and Object-based Analysis of Clouds
+
+[![Release Version](https://img.shields.io/conda/vn/conda-forge/tobac.svg)](https://anaconda.org/conda-forge/tobac)[![Download Counter](https://img.shields.io/conda/dn/conda-forge/tobac.svg)](https://anaconda.org/conda-forge/tobac)[![Documentation Status](https://readthedocs.org/projects/tobac/badge/?version=latest)](https://tobac.readthedocs.io/en/latest/?badge=latest)
+
+## What is it?
+
+_tobac_ is a Python package for identifiying, tracking and analysing of clouds and other meteorological phenomena in different types of gridded datasets. _tobac_ is unique in its ability to track phenomena using **any** variable on **any** grid, including radar data, satellite observations, and numerical model output. _tobac_ has been used in a variety of peer-reviewed [publications](https://tobac.readthedocs.io/en/latest/publications.html) and is an international, multi-institutional collaboration.
+
+## Documentation
+
+Individual features are identified as either maxima or minima in a two dimensional time varying field.
+The volume/area associated with the identified objects can be determined based on a time-varying 2D or 3D field and a threshold value. The in thre tracking step, the identified objects are linked into consistent trajectories representing the cloud over its lifecycle.
+
+Detailed documentation of the package can be found at https://tobac.readthedocs.io.
+
+Release announcements, workshop and conference announcements, and other information of interest to the broader _tobac_ users group are sent to the [tobac core group](https://groups.google.com/g/tobac/about) mailing list. If you are interested in contributing to the development of _tobac_, we invite you to join the [tobac developers](https://groups.google.com/u/1/g/tobac-developers) mailing list. Information on monthly developers' meetings and other developer discussion and announcements are sent to that list.
+
+We also have a Slack server for both users and developers. For information on joining that, please contact the _tobac_ developers mailing list, or see the information in the _tobac_ release notes sent to the _tobac_ mailing list.
+
+## Installation
+
+tobac requires Python 3, and support for Python versions before 3.9 (i.e., 3.8 and lower) is deprecated and will be removed in tobac version 1.6.
+
+The easiest way is to install the most recent version of tobac via conda and the conda-forge channel:
+
+```
+conda install -c conda-forge tobac
+```
+
+This will take care of all necessary dependencies and should do the job for most users and also allows for an easy update of the installation by
+
+```
+conda update -c conda-forge tobac
+```
+
+You can also install conda via git, either for development purposes or to use specific development branches for the Github repository.
+
+If you are using anaconda, the following command from within the cloned repository should make sure all dependencies are met and up to date:
+
+```
+conda install -c conda-forge --yes --file requirements.txt
+```
+
+You can directly install the package directly from github with pip and either of the two following commands:
+
+```
+pip install --upgrade git+ssh://git@github.com/tobac-project/tobac.git
+pip install --upgrade git+https://github.com/tobac-project/tobac.git
+```
+
+You can also clone the package with any of the two following commands
+
+```
+git clone git@github.com:tobac-project/tobac.git
+git clone https://github.com/tobac-project/tobac.git
+```
+
+and install the package from the locally cloned version:
+
+```
+pip install tobac/
+```
+
+## Contributing
+
+We encourage bug reports, questions, and code contributions. For more details on contributing, please see https://github.com/tobac-project/tobac/blob/v2.0-dev/CONTRIBUTING.md
+
+We are currently in a transition phase between versions 1.x and 2.x. v2.x will enable the use of multiple tracking methods (including TINT) and will use xarray for gridded data instead of Iris. Preliminary development on v2.x has taken place on the `v2.0-dev` branch, while work on the `main` and `RC_v1.x.x` branches (containing v1.x development) is ongoing to unify these development efforts.
+
+## Roadmap
+
+A roadmap for the future development of tobac is available here: https://github.com/tobac-project/tobac-roadmap/blob/master/tobac-roadmap-main.md

tobac-1.6.3/README.md

@@ -0,0 +1,72 @@
+# tobac - Tracking and Object-based Analysis of Clouds
+
+[![Release Version](https://img.shields.io/conda/vn/conda-forge/tobac.svg)](https://anaconda.org/conda-forge/tobac)[![Download Counter](https://img.shields.io/conda/dn/conda-forge/tobac.svg)](https://anaconda.org/conda-forge/tobac)[![Documentation Status](https://readthedocs.org/projects/tobac/badge/?version=latest)](https://tobac.readthedocs.io/en/latest/?badge=latest)
+
+## What is it?
+
+_tobac_ is a Python package for identifiying, tracking and analysing of clouds and other meteorological phenomena in different types of gridded datasets. _tobac_ is unique in its ability to track phenomena using **any** variable on **any** grid, including radar data, satellite observations, and numerical model output. _tobac_ has been used in a variety of peer-reviewed [publications](https://tobac.readthedocs.io/en/latest/publications.html) and is an international, multi-institutional collaboration.
+
+## Documentation
+
+Individual features are identified as either maxima or minima in a two dimensional time varying field.
+The volume/area associated with the identified objects can be determined based on a time-varying 2D or 3D field and a threshold value. The in thre tracking step, the identified objects are linked into consistent trajectories representing the cloud over its lifecycle.
+
+Detailed documentation of the package can be found at https://tobac.readthedocs.io.
+
+Release announcements, workshop and conference announcements, and other information of interest to the broader _tobac_ users group are sent to the [tobac core group](https://groups.google.com/g/tobac/about) mailing list. If you are interested in contributing to the development of _tobac_, we invite you to join the [tobac developers](https://groups.google.com/u/1/g/tobac-developers) mailing list. Information on monthly developers' meetings and other developer discussion and announcements are sent to that list.
+
+We also have a Slack server for both users and developers. For information on joining that, please contact the _tobac_ developers mailing list, or see the information in the _tobac_ release notes sent to the _tobac_ mailing list.
+
+## Installation
+
+tobac requires Python 3, and support for Python versions before 3.9 (i.e., 3.8 and lower) is deprecated and will be removed in tobac version 1.6.
+
+The easiest way is to install the most recent version of tobac via conda and the conda-forge channel:
+
+```
+conda install -c conda-forge tobac
+```
+
+This will take care of all necessary dependencies and should do the job for most users and also allows for an easy update of the installation by
+
+```
+conda update -c conda-forge tobac
+```
+
+You can also install conda via git, either for development purposes or to use specific development branches for the Github repository.
+
+If you are using anaconda, the following command from within the cloned repository should make sure all dependencies are met and up to date:
+
+```
+conda install -c conda-forge --yes --file requirements.txt
+```
+
+You can directly install the package directly from github with pip and either of the two following commands:
+
+```
+pip install --upgrade git+ssh://git@github.com/tobac-project/tobac.git
+pip install --upgrade git+https://github.com/tobac-project/tobac.git
+```
+
+You can also clone the package with any of the two following commands
+
+```
+git clone git@github.com:tobac-project/tobac.git
+git clone https://github.com/tobac-project/tobac.git
+```
+
+and install the package from the locally cloned version:
+
+```
+pip install tobac/
+```
+
+## Contributing
+
+We encourage bug reports, questions, and code contributions. For more details on contributing, please see https://github.com/tobac-project/tobac/blob/v2.0-dev/CONTRIBUTING.md
+
+We are currently in a transition phase between versions 1.x and 2.x. v2.x will enable the use of multiple tracking methods (including TINT) and will use xarray for gridded data instead of Iris. Preliminary development on v2.x has taken place on the `v2.0-dev` branch, while work on the `main` and `RC_v1.x.x` branches (containing v1.x development) is ongoing to unify these development efforts.
+
+## Roadmap
+
+A roadmap for the future development of tobac is available here: https://github.com/tobac-project/tobac-roadmap/blob/master/tobac-roadmap-main.md

tobac-1.6.3/pyproject.toml

@@ -0,0 +1,115 @@
+[build-system]
+requires = ["setuptools"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tobac"
+version = "1.6.3"
+authors = [
+      { name="Max Heikenfeld", email="max.heikenfeld@physics.ox.ac.uk" },
+      { name="William Jones", email="william.jones@physics.ox.ac.uk" },
+      { name="Fabian Senf", email="senf@tropos.de" },
+      { name="Sean Freeman", email="sean.freeman@uah.edu" },
+      { name="Julia Kukulies", email="kukulies@ucar.edu" },
+      { name="Kelcy Brunner", email="Kelcy.Brunner@ttu.edu" },
+      { name="Sven Starzer", email="sven.starzer@proton.me"}
+]
+description = "A package for identifying and tracking atmospheric phenomena"
+readme = "README.md"
+requires-python = ">=3.9,<3.14"
+license = {text = "BSD-3-Clause"}
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Environment :: Console",
+    "Intended Audience :: Education",
+    "Intended Audience :: Science/Research",
+    "Intended Audience :: Developers",
+    "Operating System :: POSIX :: Linux",
+    "Operating System :: MacOS :: MacOS X",
+    "Operating System :: Microsoft :: Windows",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering",
+    "Topic :: Scientific/Engineering :: Atmospheric Science",
+]
+
+# always required
+dependencies = [
+    "numpy",
+    "scipy",
+    "scikit-image",
+    "scikit-learn",
+    "pandas<3",
+    "matplotlib",
+    "scitools-iris",
+    "xarray",
+    "cartopy",
+    "trackpy",
+    "typing_extensions",
+]
+
+[project.optional-dependencies]
+# required for development
+dev = [
+    "pre-commit",
+    "black",
+    "pytest",
+    "nbconvert",
+]
+
+# required to run example notebooks
+examples = [
+    "jupyter",
+    "notebook",
+    "pytables",
+    "s3fs",
+    "arm_pyart",
+    "seaborn",
+    "h5netcdf",
+    "rioxarray",
+    "numba",
+    "dask",
+    "intake==0.7.0",
+    "intake-xarray==0.7.0",
+    "healpix",
+    "easygems",
+]
+
+# All extras combined
+all = [
+    "pre-commit",
+    "black",
+    "pytest",
+    "nbconvert",
+    "jupyter",
+    "notebook",
+    "pytables",
+    "s3fs",
+    "arm_pyart",
+    "seaborn",
+    "h5netcdf",
+    "rioxarray",
+    "numba",
+    "dask",
+    "intake==0.7.0",
+    "intake-xarray==0.7.0",
+    "healpix",
+    "easygems==0.1.2",
+]
+
+
+[project.urls]
+Homepage = "http://github.com/tobac-project/tobac"
+Documentation = "http://tobac.io"
+Issues = "http://github.com/tobac-project/tobac/issues"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["tobac*"]
+exclude = ["tmp*"]

tobac-1.6.3/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

tobac-1.6.3/tobac/__init__.py

@@ -0,0 +1,110 @@
+# from .tracking import maketrack
+import sys
+
+if sys.version_info < (3, 7):
+    warning = """ \n\n 
+    Support for Python versions less than 3.7 is deprecated. 
+    Version 1.5 of tobac will require Python 3.7 or later.
+   Python {py} detected. \n\n
+    """.format(py=".".join(str(v) for v in sys.version_info[:3]))
+
+    print(warning)
+
+from tobac.segmentation.watershed_segmentation import (
+    segmentation_3D,
+    segmentation_2D,
+    watershedding_3D,
+    watershedding_2D,
+)
+from .centerofgravity import (
+    calculate_cog,
+    calculate_cog_untracked,
+    calculate_cog_domain,
+)
+from .plotting import (
+    plot_tracks_mask_field,
+    plot_tracks_mask_field_loop,
+    plot_mask_cell_track_follow,
+    plot_mask_cell_track_static,
+    plot_mask_cell_track_static_timeseries,
+    plot_lifetime_histogram,
+    plot_lifetime_histogram_bar,
+    plot_histogram_cellwise,
+    plot_histogram_featurewise,
+    plot_mask_cell_track_3Dstatic,
+    plot_mask_cell_track_2D3Dstatic,
+    plot_mask_cell_individual_static,
+    plot_mask_cell_individual_3Dstatic,
+    animation_mask_field,
+    make_map,
+    map_tracks,
+)
+from tobac.analysis.cell_analysis import (
+    cell_statistics,
+    cog_cell,
+    lifetime_histogram,
+    histogram_cellwise,
+    velocity_histogram,
+    calculate_overlap,
+)
+from tobac.analysis.feature_analysis import (
+    histogram_featurewise,
+    calculate_nearestneighbordistance,
+    nearestneighbordistance_histogram,
+    area_histogram,
+)
+from tobac.analysis.spatial import (
+    calculate_velocity,
+    calculate_distance,
+    calculate_area,
+)
+from .utils.mask import (
+    mask_cell,
+    mask_cell_surface,
+    mask_cube_cell,
+    mask_cube_untracked,
+    mask_cube,
+    column_mask_from2D,
+    mask_features,
+    mask_features_surface,
+    mask_cube_features,
+)
+from .utils.general import (
+    get_bounding_box,
+    add_coordinates,
+    get_spacings,
+)
+from .feature_detection import feature_detection_multithreshold
+from .tracking import linking_trackpy
+from .wrapper import maketrack
+from .wrapper import tracking_wrapper
+from . import merge_split
+import importlib.metadata
+import pathlib
+
+# default version number
+__version__ = "unknown_dev_version"
+
+# Set version number
+# This version should work without needing the package installed
+try:
+    __version__ = importlib.metadata.version(__package__ or __name__)
+except importlib.metadata.PackageNotFoundError:
+    # need to get version directly from text file
+    try:
+        import tomllib
+
+        pyproject_toml_file_name = (
+            pathlib.Path(__file__).parent.parent / "pyproject.toml"
+        )
+        if pyproject_toml_file_name.exists() and pyproject_toml_file_name.is_file():
+            with open(pyproject_toml_file_name, "rb") as f:
+                toml_data = tomllib.load(f)
+                if "project" in toml_data and "version" in toml_data["project"]:
+                    __version__ = toml_data["project"]["version"]
+
+    except ImportError:
+        # on python <3.11 but not installing tobac.
+        # don't bother giving precise version number.
+        __version__ = "unknown_dev_version"
+    pass

tobac-1.6.3/tobac/analysis/__init__.py

@@ -0,0 +1,31 @@
+"""Provide tools to analyse and visualize the tracked objects.
+This module provides a set of routines that enables performing analyses
+and deriving statistics for individual tracks, such as the time series
+of integrated properties and vertical profiles. It also provides
+routines to calculate summary statistics of the entire population of
+tracked features in the field like histograms of areas/volumes
+or mass and a detailed cell lifetime analysis. These analysis
+routines are all built in a modular manner. Thus, users can reuse the
+most basic methods for interacting with the data structure of the
+package in their own analysis procedures in Python. This includes
+functions performing simple tasks like looping over all identified
+objects or trajectories and masking arrays for the analysis of
+individual features. Plotting routines include both visualizations
+for individual convective cells and their properties. [1]_
+
+References
+----------
+.. Heikenfeld, M., Marinescu, P. J., Christensen, M.,
+   Watson-Parris, D., Senf, F., van den Heever, S. C.
+   & Stier, P. (2019). tobac 1.2: towards a flexible
+   framework for tracking and analysis of clouds in
+   diverse datasets. Geoscientific Model Development,
+   12(11), 4551-4570.
+
+Notes
+-----
+"""
+
+from tobac.analysis.cell_analysis import *
+from tobac.analysis.feature_analysis import *
+from tobac.analysis.spatial import *