Merging RC_v1.4.0 into main

.coveragerc

@@ -1,3 +1,5 @@
 [run]
 source=tobac
-omit = tobac/tests/*
+omit =
+        tobac/tests/*
+        setup.py

.github/workflows/check_formatting.yml

@@ -9,6 +9,6 @@ jobs:
         with:
           python-version: '3.8'
       - run: pip install .
-      - run: pip install black
+      - run: pip install black==22.6.0 
       - run: black tobac --check
 

.github/workflows/codecov-CI.yml

@@ -26,7 +26,7 @@ jobs:
       run: mamba install --quiet --yes --file conda-requirements.txt coverage pytest-cov &&
            python -m coverage run -m pytest --cov=./ --cov-report=xml
     - name: Upload Coverage to Codecov
-      uses: codecov/codecov-action@v2
+      uses: codecov/codecov-action@v3
       with: 
         fail_ci_if_error: true
         flags: unittests

.gitignore

@@ -2,4 +2,5 @@
 __pycache__
 .vscode
 htmlcov
-.coverage
+.coverage
+build

.readthedocs.yml

@@ -0,0 +1,7 @@
+version: 2
+formats: all
+python:
+  version: 3
+  install:
+    - requirements: doc/requirements.txt
+  system_packages: true

.zenodo.json

@@ -0,0 +1,85 @@
+{
+    "title": "tobac - Tracking and Object-based Analysis of Clouds",
+    "description": "tobac is a Python package to identify, track and analyze clouds in different types of gridded datasets, such as 3D model output from cloud-resolving model simulations or 2D data from satellite retrievals.",
+    "creators": [
+        {
+            "name": "tobac Community"
+        },
+        {
+            "name": "Heikenfeld, Max",
+            "affiliation": "University of Oxford",
+            "orcid": "0000-0001-8124-8048"
+        },
+        {
+            "name": "Marinescu, Peter J.",
+            "affiliation": "Colorado State University",
+            "orcid": "0000-0002-5842-969X"
+        },
+        {
+            "name": "Freeman, Sean W.",
+            "affiliation": "Colorado State University",
+            "orcid": "0000-0002-7398-1597"
+        },
+        {
+            "name": "Kukulies, Julia",
+            "affiliation": "University of Gothenburg (Sweden)",
+            "orcid": "0000-0001-6084-0069"
+        },
+        {
+            "name": "Jones, William K.",
+            "affiliation": "University of Oxford",
+            "orcid": "0000-0001-9786-3723"
+        },
+        {
+            "name": "Senf, Fabian",
+            "affiliation": "Leibniz Institute for Tropospheric Research, Leipzig (Germany)",
+            "orcid": "0000-0003-1685-2657"
+        },
+        {
+            "name": "Bruning, Eric",
+            "affiliation": "Texas Tech University",
+            "orcid": "0000-0003-1959-442X"
+        },
+        {
+            "name": "Brunner, Kelcy",
+            "affiliation": "Texas Tech University",
+            "orcid": "0000-0003-3938-0963"
+        },
+        {
+            "name": "Collis, Scott M.",
+            "affiliation": "Argonne National Laboratory",
+            "orcid": "0000-0002-2303-687X"
+        },
+        {
+            "name": "Pfeifer, Nils",
+            "affiliation": "Leibniz Institute for Tropospheric Research, Leipzig (Germany)",
+            "orcid": "0000-0002-5350-1445"
+        },
+        {
+            "name": "Raut, Bhupendra A.",
+            "affiliation": "Northwestern-Argonne Institute of Science and Engineering, Argonne National Laboratory",
+            "orcid": "0000-0001-5598-1393"
+        },
+        {
+            "name": "Stier, Philip",
+            "affiliation": "University of Oxford",
+            "orcid": "0000-0002-1191-0128"
+        },
+        {
+            "name": "van den Heever, Sue C.",
+            "affiliation": "Colorado State University",
+            "orcid": "0000-0001-9843-3864"
+        },
+        {
+            "name": "Zhang, Xin",
+            "affiliation": "Nanjing University of Information Science & Technology (China)",
+            "orcid": "0000-0002-1756-6620"
+        }
+    ],
+    "license": "BSD-3-Clause",
+    "keywords": [
+        "cloud tracking"
+    ],
+    "access_right": "open",
+    "upload_type": "software"
+}

CHANGELOG.md

@@ -1,5 +1,42 @@
 ### Tobac Changelog
 
+_**Version 1.4.0:**_
+
+**Enhancements**
+
+- Added the ability to detect feature mergers and splits ([#136](https://github.com/tobac-project/tobac/pull/136))
+- Added spectral filtering of input data to feature detection (#137)
+- Substantial improvements to documentation ([#138](https://github.com/tobac-project/tobac/pull/138), [#150](https://github.com/tobac-project/tobac/pull/150), [#155](https://github.com/tobac-project/tobac/pull/155), [#173](https://github.com/tobac-project/tobac/pull/173), [#189](https://github.com/tobac-project/tobac/pull/189), [#195](https://github.com/tobac-project/tobac/pull/195), [#197](https://github.com/tobac-project/tobac/pull/197))
+- Added a new function to combine feature dataframes when feature detection is run in parallel ([#186](https://github.com/tobac-project/tobac/pull/186))
+
+**Bug fixes**
+
+- Reset the adaptive search parameters back to default when using adaptive trackpy tracking ([#168](https://github.com/tobac-project/tobac/pull/168))
+- Added checks to make sure that both `adaptive_step` and `adaptive_stop` are set when using adaptive tracking ([#168](https://github.com/tobac-project/tobac/pull/168))
+- Added error raising when trying to use the not yet implemented extrapolation feature ([#177](https://github.com/tobac-project/tobac/pull/177))
+- Fixed a bug where `min_distance` did not work in feature detection ([#187](https://github.com/tobac-project/tobac/pull/187))
+- Fixed a bug where feature detection output different feature locations depending on the order that thresholds are passed in ([#199](https://github.com/tobac-project/tobac/pull/199))
+
+**Documentation**
+
+- Updated docstrings to NumPy format ([#138](https://github.com/tobac-project/tobac/pull/138), [#155](https://github.com/tobac-project/tobac/pull/155), [#173](https://github.com/tobac-project/tobac/pull/173))
+- Enabled API documentation generation ([#150](https://github.com/tobac-project/tobac/pull/150))
+- Enhanced documentation of feature detection and segmentation parameters ([#150](https://github.com/tobac-project/tobac/pull/150))
+- Added contributors to zenodo ([#139](https://github.com/tobac-project/tobac/pull/139))
+- Added `__version__` as a parameter ([#175](https://github.com/tobac-project/tobac/pull/175))
+- Updated the feature detection docstrings to add clarification around units ([#189](https://github.com/tobac-project/tobac/pull/189))
+- Added documentation on why sometimes no features are segmented ([#195](https://github.com/tobac-project/tobac/pull/195))
+- Added updates to README file, including linking the google groups ([#162](https://github.com/tobac-project/tobac/pull/162), [#197](https://github.com/tobac-project/tobac/pull/197))
+
+**Repository enhancements**
+
+- Specified the version of `black` to use for validating formatting during CI ([#161](https://github.com/tobac-project/tobac/pull/161))
+- Lowered threshold before code coverage CI fails on pull requests ([#159](https://github.com/tobac-project/tobac/pull/159))
+
+**Deprecations**
+
+- Support for Python 3.6 and earlier is now deprecated and will be removed in v1.5.0 ([#193](https://github.com/tobac-project/tobac/pull/193))
+
 _**Version 1.3.3:**_
 
 **Bug fixes**
@@ -18,7 +55,6 @@ _**Version 1.3.2:**_
 - Added automatic code coverage reports [#124](https://github.com/tobac-project/tobac/pull/124)
 - Added automatic building of readthedocs documentation on pull requests
 
-
 _**Version 1.3.1:**_
 
 **Enhancements**

CONTRIBUTING.md

@@ -35,7 +35,7 @@ Please create a new issue on [GitHub](https://github.com/climate-processes/tobac
 * Before you start a pull request, please make sure that you added [numpydoc docstrings](#docstringExample) to your functions. This way the api documentation will be parsed properly.
 * If it is a larger change or an newly added feature or workflow, please place an example of use in the [tobac-tutorials](https://github.com/climate-processes/tobac-tutorials) repository or adapt the existing examples there.
 * If necessary add a folder or modify a file.
-* The code should be PEP 8 compliant, as this facilitates our collaboration. Please use the latest version of [black](https://black.readthedocs.io/en/stable/) to format your code. When you submit a pull request, all files are checked for formatting.
+* The code should be PEP 8 compliant, as this facilitates our collaboration. Please use the first stable version (22.6.0) of [black](https://black.readthedocs.io/en/stable/) to format your code. When you submit a pull request, all files are checked for formatting.
 * The tobac repository is set up with pre-commit hooks to automatically format your code when commiting changes. Please run the command "pre-commit install" in the root directory of tobac to set up pre-commit formatting.
 
 We aim to respond to all new issues/pull requests as soon as possible, however at times this is not possible due to work commitments.

README.md

@@ -1,23 +1,26 @@
 tobac - Tracking and Object-based Analysis of Clouds
 ======
-[![Documentation Status](https://readthedocs.org/projects/tobac/badge/?version=latest)](https://tobac.readthedocs.io/en/latest/?badge=latest)[![Build Status](https://travis-ci.org/climate-processes/tobac.svg?branch=master)](https://travis-ci.org/climate-processes/tobac)
+[![Documentation Status](https://readthedocs.org/projects/tobac/badge/?version=latest)](https://tobac.readthedocs.io/en/latest/?badge=latest)[![Download Counter](https://anaconda.org/conda-forge/tobac/)](https://anaconda.org/conda-forge/tobac/badges/downloads.svg)
 
 What is it?
 -----------
 
-**tobac** is a Python package for identifiying, tracking and analysing of clouds in different types of gridded datasets, i.e. 3D model output from cloud resolving model simulations or 2D data of satellite observations.
+*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/rc_v1.4.0/publications.html) and is an international, multi-institutional collaboration. 
 
 Documentation
 -------------
-Individual features are indentified as either maxima or minima in a two dimensional time varying field.
+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 now works for both Python 3 and Python 2 installations.
+tobac requires Python 3, and support for Python versions before 3.7 (i.e., 3.6 and lower) is deprecated and will be removed in tobac version 1.5.
 
 The easiest way is to install the most recent version of tobac via conda and the conda-forge channel:
 ```
@@ -37,13 +40,13 @@ conda install -c conda-forge --yes --file conda-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/climate-processes/tobac.git
-pip install --upgrade git+https://github.com/climate-processes/tobac.git
+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:climate-processes/tobac.git
-git clone https://github.com/climate-processes/tobac.git
+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:
 ```
@@ -52,12 +55,10 @@ pip install tobac/
 
 Contributing
 ------------
-The current development branch for minor updates to tobac v1 is dev.
-
-Preliminary development of the future major update to tobac is v2.0-dev.
+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
 
-For more details on contributing, please see https://github.com/climate-processes/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/fsenf/tobac-roadmap/blob/master/tobac-roadmap-main.md
+A roadmap for the future development of tobac is available here: https://github.com/tobac-project/tobac-roadmap/blob/master/tobac-roadmap-main.md

codecov.yml

@@ -0,0 +1,22 @@
+# Codecov.io settings 
+
+coverage:
+  status:
+    project:
+      default:
+        # basic settings
+        # auto target means look at deltas from previous
+        target: auto
+        # Threshold we can drop coverage before failing CI
+        threshold: 1%
+        base: auto 
+        flags: 
+          - unit
+        paths: 
+          - "tobac"
+
+# what folders and files to ignore
+ignore:
+  - "tobac/tests/.*"
+  - "setup.py"
+

doc/_static/theme_overrides.css

@@ -0,0 +1,18 @@
+/* from https://github.com/readthedocs/sphinx_rtd_theme/issues/117#issuecomment-41506687 */
+/* with augmentations from https://github.com/readthedocs/sphinx_rtd_theme/issues/117#issuecomment-153083280 */
+/* override table width restrictions */
+@media screen and (min-width: 767px) {
+
+    .wy-table-responsive table td {
+      /* !important prevents the common CSS stylesheets from
+         overriding this as on RTD they are loaded after this stylesheet */
+        white-space: normal !important;
+     }
+
+    .wy-table-responsive {
+        max-width: 100%;
+        overflow: visible !important;
+
+    }
+
+}

doc/analysis.rst

@@ -1,5 +1,7 @@
+..
+    Documentation of analysis functions
+    TODO: include descriptions of the analysis functions and examples
 Analysis
-=======
-tobac provides several analysis functions that allow for the calculation of important quantities based on the tracking results. This includes the calculation of important properties of the tracked objects such as cloud lifetimes, cloud areas/volumes, but also allows for a convenient calculation of statistics for arbitratry fields of the same shape as as the input data used for the tracking analysis.
-
+=========
+tobac provides several analysis functions that allow for the calculation of important quantities based on the tracking results. This includes the calculation of properties such as feature lifetimes and feature areas/volumes, but also allows for a convenient calculation of statistics for arbitrary fields of the same shape as as the input data used for the tracking analysis.
 

doc/big_datasets.rst

@@ -0,0 +1,11 @@
+Handling Large Datasets
+-------------------------------------
+
+Often, one desires to use *tobac* to identify and track features in large datasets ("big data"). This documentation strives to suggest various methods for doing so efficiently. Current versions of *tobac* do not allow for out-of-memory computation, meaning that these strategies may need to be employed for both computational and memory reasons. 
+
+.. _Split Feature Detection:
+=======================
+Split Feature Detection
+=======================
+Current versions of threshold feature detection (see :doc:`feature_detection_overview`) are time independent, meaning that one can parallelize feature detection across all times (although not across space). *tobac* provides the :py:meth:`tobac.utils.combine_tobac_feats` function to combine a list of dataframes produced by a parallelization method (such as :code:`jug` or :code:`multiprocessing.pool`) into a single combined dataframe suitable to perform tracking with. 
+

doc/conf.py

@@ -0,0 +1,56 @@
+'''This file is used to configure the Sphinx build of our documentation.
+The documentation on setting this up is here: https://www.sphinx-doc.org/en/master/usage/configuration.html 
+'''
+
+# This is the standard readthedocs theme.
+import sphinx_rtd_theme
+import sys, os
+
+sys.path.insert(0, os.path.abspath('extensions'))
+
+# What Sphinx extensions do we need
+extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.todo',
+              'sphinx.ext.coverage', 'sphinx.ext.imgmath', 'sphinx.ext.ifconfig',
+              'sphinx_rtd_theme','sphinx.ext.napoleon', 'nbsphinx']
+
+
+html_theme = "sphinx_rtd_theme"
+
+html_static_path = ['_static']
+
+
+project = u'tobac'
+
+master_doc = 'index'
+
+# allow dropdowns
+collapse_navigation = False
+
+# Include our custom CSS (currently for special table config)
+def setup(app):
+   app.add_css_file("theme_overrides.css")
+
+# This should include all modules used in tobac. These are dummy imports,
+# but should include both required and optional dependencies.
+autodoc_mock_imports = ['numpy', 'scipy', 'scikit-image', 'pandas', 'pytables', 'matplotlib', 'iris',
+                        'cf-units', 'xarray', 'cartopy', 'trackpy', 'numba']
+
+sys.path.insert(0, os.path.abspath("../"))
+
+# Napoleon settings for configuring the Napoleon extension
+# See documentation here:
+# https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html
+napoleon_google_docstring = True
+napoleon_numpy_docstring = True
+napoleon_include_init_with_doc = False
+napoleon_include_private_with_doc = False
+napoleon_include_special_with_doc = True
+napoleon_use_admonition_for_examples = False
+napoleon_use_admonition_for_notes = False
+napoleon_use_admonition_for_references = False
+napoleon_use_ivar = False
+napoleon_use_param = True
+napoleon_use_rtype = True
+napoleon_preprocess_types = False
+napoleon_type_aliases = None
+napoleon_attr_annotations = True