Merge pull request #439 from tobac-project/RC_v1.5.x

Merge `RC_v1.5.x` into `RC_v1.6.0`

Author: freemansw1

.github/workflows/codecov-CI.yml

@@ -27,7 +27,7 @@ jobs:
           mamba install --quiet --yes --file requirements.txt coverage pytest-cov &&
           python -m coverage run -m pytest --cov=./ --cov-report=xml
       - name: Upload Coverage to Codecov
-        uses: codecov/codecov-action@v3
+        uses: codecov/codecov-action@v4
         with:
           token: ${{ secrets.CODECOV_TOKEN }}
           fail_ci_if_error: true

.zenodo.json

@@ -23,7 +23,7 @@
 
         {
             "name": "Kukulies, Julia",
-            "affiliation": "University of Gothenburg (Sweden)",
+            "affiliation": "NSF National Center for Atmospheric Research",
             "orcid": "0000-0001-6084-0069"
         },
         {

CHANGELOG.md

@@ -1,5 +1,26 @@
 ### Tobac Changelog
 
+_**Version 1.5.3:**_
+
+**Enhancements for Users**
+
+- Update `calculate_area` to allow the calculation of the projected 2D area of 3D objects, and enhance bulk statistics to allow calculation of statistics on the projected footprint on 2D fields [#378](https://github.com/tobac-project/tobac/pull/378)
+
+**Bug fixes**
+
+- Fix a bug in `get_spacing` that would return a negative value if one coordinate was in ascending order and the other in descending order, and fix other bugs where the wrong coordinate was referenced [#400](https://github.com/tobac-project/tobac/pull/400)
+
+**Documentation**
+
+- Re-integration of notebooks from the tobac-tutorials repo [#334](https://github.com/tobac-project/tobac/pull/334)
+- Add example gallery to readthedocs page [#411](https://github.com/tobac-project/tobac/pull/411)
+
+**Internal Enhancements**
+
+- Add ability to save whether iris to xarray conversion ocurred and update decorators to allow keyword parameters [#380](https://github.com/tobac-project/tobac/pull/380)
+- Reorganisation of analysis tools into analysis package [#378](https://github.com/tobac-project/tobac/pull/378)
+
+
 _**Version 1.5.2:**_
 
 **Enhancements for Users**

CONTRIBUTING.md

@@ -2,73 +2,48 @@
 
 __Welcome! We are very happy that you are interested in our project and thanks for taking time to contribute! :)__
 
-We are currently reorganizing our project. So, please check our modifications later.
-
 
 ## Getting Started
 ### Installation & Environment details
-You will find them in the [README.md](https://github.com/climate-processes/tobac/blob/master/README.md).
+You will find them in the [README.md](https://github.com/tobac-project/tobac/blob/master/README.md).
 
 ### Tutorials
-Tutorials have been prepared to provide you further inside to `tobac`s functionality. Please visit the separate [tobac-tutorials](https://github.com/climate-processes/tobac-tutorials) repository here on Github.
-
+Tutorials have been prepared to provide you further inside to `tobac`s functionality. Please have a look in the 
+[examples folder](https://github.com/tobac-project/tobac/tree/main/examples). 
 
 ### Documentation
 You will find our documentation at [https://tobac.readthedocs.io](https://tobac.readthedocs.io).
 
 ### Testing
 The tests are located in the [tests folder](https://github.com/climate-processes/tobac/tree/master/tobac/tests).
 
-
 ## Reporting Bugs
-Please create a new issue on [GitHub](https://github.com/climate-processes/tobac/issues) if it is not listed there, yet.
+Please create a new issue on [GitHub](https://github.com/tobac-project/tobac/issues) if it is not listed there, yet.
 
 ### How to write a good Bug Report?
 * Give it a clear descriptive title.
 * Copy and paste the error message.
 * Describe the steps for reproducing the problem and give an specific example.  
-* Optional: Make a suggestion to fix it.
-
+* Optional: Make a suggestion to fix it. 
 
 ## How to Submit Changes
-* Please read the [README.md](https://github.com/climate-processes/tobac/blob/master/README.md) first, to learn about our project goals and check the [changelog.md]().
-* 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.
+* Have a look at [our roadmap](https://github.com/tobac-project/tobac-roadmap/blob/master/tobac-roadmap-main.md) first, 
+to learn about our project goals and check the 
+[changelog.md](https://github.com/tobac-project/tobac/blob/main/CHANGELOG.md).
+* More details on the code structure and further help for code contributions can be found in our [developer 
+guide](https://tobac.readthedocs.io/code_structure.html)
+* Before you start a pull request, please make sure that you added [numpydoc 
+docstrings](https://numpydoc.readthedocs.io/en/latest/format.html) to your 
+functions. See [docstring example in the developer guide](https://tobac.readthedocs.io/contributing.html). This way the 
+api documentation will be parsed properly.
+* If it is a larger change or an newly added feature or workflow, please add an example in the [example 
+folder](https://github.com/tobac-project/tobac/tree/main/examples) or adapt the existing examples there.
 * 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.
-
-### Numpydoc Example <a name='docstringExample'>
-```python
-  
-   '''
-   calculate centre of gravity and mass forech individual tracked cell in the simulation
-
-
-    Parameters
-    ----------
-    tracks : pandas.DataFram
-        DataFrame containing trajectories of cell centres
-        
-    param mass : iris.cube.Cube
-        cube of quantity (need coordinates 'time', 'geopotential_height','projection_x_coordinate' and 
-        'projection_y_coordinate')
-        
-    param mask : iris.cube.Cube
-        cube containing mask (int > where belonging to cloud volume, 0 everywhere else )
-
+We aim to respond to all new issues/pull requests as soon as possible, however sometimes this is not possible due to work commitments.
 
-    Returns
-    -------
-    track_out : pandas.DataFrame
-        Dataframe containing t,x,y,z positions of centre of gravity and total cloud mass each tracked cells 
-        at each timestep
-    
-    '''
 
-```
 
 ## Slack
 In addition to the workflow here on Github, there's a tobac workspace on Slack [tobac-dev.slack.com](tobac-dev.slack.com) that we use for some additional communication around the project. Please join us there to stay updated about all things tobac that go beyond the detailed work on the code.

doc/_static/thumbnails/Basics_Idealized-Case-1_Tracking-of-a-Test-Blob-in-2D_Thumbnail.png

@@ -17,10 +17,10 @@
    "execution_count": 1,
    "metadata": {
     "execution": {
-     "iopub.execute_input": "2024-02-17T13:15:49.602971Z",
-     "iopub.status.busy": "2024-02-17T13:15:49.602462Z",
-     "iopub.status.idle": "2024-02-17T13:15:51.108332Z",
-     "shell.execute_reply": "2024-02-17T13:15:51.106184Z"
+     "iopub.execute_input": "2024-03-22T17:18:35.329188Z",
+     "iopub.status.busy": "2024-03-22T17:18:35.328690Z",
+     "iopub.status.idle": "2024-03-22T17:18:36.372987Z",
+     "shell.execute_reply": "2024-03-22T17:18:36.372118Z"
     }
    },
    "outputs": [],
@@ -42,18 +42,18 @@
    "execution_count": 2,
    "metadata": {
     "execution": {
-     "iopub.execute_input": "2024-02-17T13:15:51.115152Z",
-     "iopub.status.busy": "2024-02-17T13:15:51.114024Z",
-     "iopub.status.idle": "2024-02-17T13:15:54.249193Z",
-     "shell.execute_reply": "2024-02-17T13:15:54.246812Z"
+     "iopub.execute_input": "2024-03-22T17:18:36.376438Z",
+     "iopub.status.busy": "2024-03-22T17:18:36.376057Z",
+     "iopub.status.idle": "2024-03-22T17:18:38.247466Z",
+     "shell.execute_reply": "2024-03-22T17:18:38.239280Z"
     }
    },
    "outputs": [
     {
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "using tobac version 1.5.2\n"
+      "using tobac version 1.5.3\n"
      ]
     }
    ],
@@ -68,10 +68,10 @@
    "execution_count": 3,
    "metadata": {
     "execution": {
-     "iopub.execute_input": "2024-02-17T13:15:54.331271Z",
-     "iopub.status.busy": "2024-02-17T13:15:54.324629Z",
-     "iopub.status.idle": "2024-02-17T13:15:54.338758Z",
-     "shell.execute_reply": "2024-02-17T13:15:54.336986Z"
+     "iopub.execute_input": "2024-03-22T17:18:38.285861Z",
+     "iopub.status.busy": "2024-03-22T17:18:38.285093Z",
+     "iopub.status.idle": "2024-03-22T17:18:38.294187Z",
+     "shell.execute_reply": "2024-03-22T17:18:38.292554Z"
     }
    },
    "outputs": [],
@@ -98,10 +98,10 @@
    "execution_count": 4,
    "metadata": {
     "execution": {
-     "iopub.execute_input": "2024-02-17T13:15:54.351167Z",
-     "iopub.status.busy": "2024-02-17T13:15:54.349280Z",
-     "iopub.status.idle": "2024-02-17T13:15:54.367183Z",
-     "shell.execute_reply": "2024-02-17T13:15:54.365164Z"
+     "iopub.execute_input": "2024-03-22T17:18:38.322117Z",
+     "iopub.status.busy": "2024-03-22T17:18:38.321283Z",
+     "iopub.status.idle": "2024-03-22T17:18:38.331190Z",
+     "shell.execute_reply": "2024-03-22T17:18:38.324702Z"
     }
    },
    "outputs": [],
@@ -114,10 +114,10 @@
    "execution_count": 5,
    "metadata": {
     "execution": {
-     "iopub.execute_input": "2024-02-17T13:15:54.380965Z",
-     "iopub.status.busy": "2024-02-17T13:15:54.372136Z",
-     "iopub.status.idle": "2024-02-17T13:15:54.405551Z",
-     "shell.execute_reply": "2024-02-17T13:15:54.401789Z"
+     "iopub.execute_input": "2024-03-22T17:18:38.344343Z",
+     "iopub.status.busy": "2024-03-22T17:18:38.344007Z",
+     "iopub.status.idle": "2024-03-22T17:18:38.351035Z",
+     "shell.execute_reply": "2024-03-22T17:18:38.349141Z"
     }
    },
    "outputs": [],
@@ -149,10 +149,10 @@
    "execution_count": 6,
    "metadata": {
     "execution": {
-     "iopub.execute_input": "2024-02-17T13:15:54.424094Z",
-     "iopub.status.busy": "2024-02-17T13:15:54.421895Z",
-     "iopub.status.idle": "2024-02-17T13:15:54.722903Z",
-     "shell.execute_reply": "2024-02-17T13:15:54.721785Z"
+     "iopub.execute_input": "2024-03-22T17:18:38.370773Z",
+     "iopub.status.busy": "2024-03-22T17:18:38.366590Z",
+     "iopub.status.idle": "2024-03-22T17:18:38.505880Z",
+     "shell.execute_reply": "2024-03-22T17:18:38.504723Z"
     }
    },
    "outputs": [],
@@ -165,10 +165,10 @@
    "execution_count": 7,
    "metadata": {
     "execution": {
-     "iopub.execute_input": "2024-02-17T13:15:54.730863Z",
-     "iopub.status.busy": "2024-02-17T13:15:54.729948Z",
-     "iopub.status.idle": "2024-02-17T13:15:54.754780Z",
-     "shell.execute_reply": "2024-02-17T13:15:54.754021Z"
+     "iopub.execute_input": "2024-03-22T17:18:38.525114Z",
+     "iopub.status.busy": "2024-03-22T17:18:38.522164Z",
+     "iopub.status.idle": "2024-03-22T17:18:38.564211Z",
+     "shell.execute_reply": "2024-03-22T17:18:38.562792Z"
     }
    },
    "outputs": [
@@ -223,7 +223,7 @@
        "      margin-top: 7px;\n",
        "  }\n",
        "</style>\n",
-       "<table class=\"iris\" id=\"5155089680\">\n",
+       "<table class=\"iris\" id=\"5282387344\">\n",
        "    <tr class=\"iris\">\n",
        "<th class=\"iris iris-word-cell\">Surface Precipitation Average (mm h-1)</th>\n",
        "<th class=\"iris iris-word-cell\">time</th>\n",
@@ -333,10 +333,10 @@
    "execution_count": 8,
    "metadata": {
     "execution": {
-     "iopub.execute_input": "2024-02-17T13:15:54.762881Z",
-     "iopub.status.busy": "2024-02-17T13:15:54.759869Z",
-     "iopub.status.idle": "2024-02-17T13:15:54.770105Z",
-     "shell.execute_reply": "2024-02-17T13:15:54.767917Z"
+     "iopub.execute_input": "2024-03-22T17:18:38.578722Z",
+     "iopub.status.busy": "2024-03-22T17:18:38.575755Z",
+     "iopub.status.idle": "2024-03-22T17:18:38.586793Z",
+     "shell.execute_reply": "2024-03-22T17:18:38.584944Z"
     }
    },
    "outputs": [],
@@ -372,10 +372,10 @@
    "execution_count": 9,
    "metadata": {
     "execution": {
-     "iopub.execute_input": "2024-02-17T13:15:54.773843Z",
-     "iopub.status.busy": "2024-02-17T13:15:54.773535Z",
-     "iopub.status.idle": "2024-02-17T13:15:54.788479Z",
-     "shell.execute_reply": "2024-02-17T13:15:54.787618Z"
+     "iopub.execute_input": "2024-03-22T17:18:38.608207Z",
+     "iopub.status.busy": "2024-03-22T17:18:38.607420Z",
+     "iopub.status.idle": "2024-03-22T17:18:38.618440Z",
+     "shell.execute_reply": "2024-03-22T17:18:38.617527Z"
     }
    },
    "outputs": [],
@@ -412,10 +412,10 @@
    "execution_count": 10,
    "metadata": {
     "execution": {
-     "iopub.execute_input": "2024-02-17T13:15:54.796799Z",
-     "iopub.status.busy": "2024-02-17T13:15:54.796072Z",
-     "iopub.status.idle": "2024-02-17T13:15:54.803867Z",
-     "shell.execute_reply": "2024-02-17T13:15:54.803047Z"
+     "iopub.execute_input": "2024-03-22T17:18:38.635746Z",
+     "iopub.status.busy": "2024-03-22T17:18:38.635394Z",
+     "iopub.status.idle": "2024-03-22T17:18:38.642691Z",
+     "shell.execute_reply": "2024-03-22T17:18:38.640392Z"
     }
    },
    "outputs": [],
@@ -438,10 +438,10 @@
    "execution_count": 11,
    "metadata": {
     "execution": {
-     "iopub.execute_input": "2024-02-17T13:15:54.816776Z",
-     "iopub.status.busy": "2024-02-17T13:15:54.814862Z",
-     "iopub.status.idle": "2024-02-17T13:15:54.833273Z",
-     "shell.execute_reply": "2024-02-17T13:15:54.830306Z"
+     "iopub.execute_input": "2024-03-22T17:18:38.665578Z",
+     "iopub.status.busy": "2024-03-22T17:18:38.663868Z",
+     "iopub.status.idle": "2024-03-22T17:18:38.672653Z",
+     "shell.execute_reply": "2024-03-22T17:18:38.671135Z"
     }
    },
    "outputs": [],
@@ -454,10 +454,10 @@
    "execution_count": 12,
    "metadata": {
     "execution": {
-     "iopub.execute_input": "2024-02-17T13:15:54.839903Z",
-     "iopub.status.busy": "2024-02-17T13:15:54.839490Z",
-     "iopub.status.idle": "2024-02-17T13:16:19.461680Z",
-     "shell.execute_reply": "2024-02-17T13:16:19.460304Z"
+     "iopub.execute_input": "2024-03-22T17:18:38.691608Z",
+     "iopub.status.busy": "2024-03-22T17:18:38.691219Z",
+     "iopub.status.idle": "2024-03-22T17:18:56.451127Z",
+     "shell.execute_reply": "2024-03-22T17:18:56.450419Z"
     }
    },
    "outputs": [
@@ -504,10 +504,10 @@
    "execution_count": 13,
    "metadata": {
     "execution": {
-     "iopub.execute_input": "2024-02-17T13:16:19.466025Z",
-     "iopub.status.busy": "2024-02-17T13:16:19.465158Z",
-     "iopub.status.idle": "2024-02-17T13:16:19.491494Z",
-     "shell.execute_reply": "2024-02-17T13:16:19.490396Z"
+     "iopub.execute_input": "2024-03-22T17:18:56.455395Z",
+     "iopub.status.busy": "2024-03-22T17:18:56.454610Z",
+     "iopub.status.idle": "2024-03-22T17:18:56.477335Z",
+     "shell.execute_reply": "2024-03-22T17:18:56.476369Z"
     }
    },
    "outputs": [