Merge branch 'main' into indexes-repr-join-text

Author: keewis

.github/workflows/ci-additional.yaml

@@ -25,7 +25,7 @@ jobs:
       - uses: actions/checkout@v3
         with:
           fetch-depth: 2
-      - uses: xarray-contrib/ci-trigger@v1.1
+      - uses: xarray-contrib/ci-trigger@v1
         id: detect-trigger
         with:
           keyword: "[skip-ci]"

.github/workflows/ci.yaml

@@ -25,7 +25,7 @@ jobs:
       - uses: actions/checkout@v3
         with:
           fetch-depth: 2
-      - uses: xarray-contrib/ci-trigger@v1.1
+      - uses: xarray-contrib/ci-trigger@v1
         id: detect-trigger
         with:
           keyword: "[skip-ci]"

.github/workflows/upstream-dev-ci.yaml

@@ -27,7 +27,7 @@ jobs:
       - uses: actions/checkout@v3
         with:
           fetch-depth: 2
-      - uses: xarray-contrib/ci-trigger@v1.1
+      - uses: xarray-contrib/ci-trigger@v1
         id: detect-trigger
         with:
           keyword: "[test-upstream]"
@@ -49,8 +49,6 @@ jobs:
       fail-fast: false
       matrix:
         python-version: ["3.10"]
-    outputs:
-      artifacts_availability: ${{ steps.status.outputs.ARTIFACTS_AVAILABLE }}
     steps:
       - uses: actions/checkout@v3
         with:
@@ -74,110 +72,21 @@ jobs:
           conda info -a
           conda list
           python xarray/util/print_versions.py
-      - name: import xarray
+      - name: Import xarray
         run: |
           python -c 'import xarray'
       - name: Run Tests
         if: success()
         id: status
         run: |
           python -m pytest --timeout=60 -rf \
-            --report-log output-${{ matrix.python-version }}-log.jsonl \
-            || (
-              echo '::set-output name=ARTIFACTS_AVAILABLE::true' && false
-            )
-      - name: Upload artifacts
+            --report-log output-${{ matrix.python-version }}-log.jsonl
+      - name: Generate and publish the report
         if: |
           failure()
           && steps.status.outcome == 'failure'
           && github.event_name == 'schedule'
-          && github.repository == 'pydata/xarray'
-        uses: actions/upload-artifact@v3
-        with:
-          name: output-${{ matrix.python-version }}-log.jsonl
-          path: output-${{ matrix.python-version }}-log.jsonl
-          retention-days: 5
-
-  report:
-    name: report
-    needs: upstream-dev
-    if: |
-      failure()
-      && github.event_name == 'schedule'
-      && needs.upstream-dev.outputs.artifacts_availability == 'true'
-    runs-on: ubuntu-latest
-    defaults:
-      run:
-        shell: bash
-    steps:
-      - uses: actions/checkout@v3
-      - uses: actions/setup-python@v4
+          && github.repository_owner == 'pydata'
+        uses: xarray-contrib/issue-from-pytest-log@v0.1
         with:
-          python-version: "3.x"
-      - uses: actions/download-artifact@v3
-        with:
-          path: /tmp/workspace/logs
-      - name: Move all log files into a single directory
-        run: |
-          rsync -a /tmp/workspace/logs/output-*/ ./logs
-          ls -R ./logs
-      - name: install dependencies
-        run: |
-          python -m pip install pytest
-      - name: Parse logs
-        run: |
-          shopt -s globstar
-          python .github/workflows/parse_logs.py logs/**/*-log*
-          cat pytest-logs.txt
-      - name: Report failures
-        uses: actions/github-script@v6
-        with:
-          github-token: ${{ secrets.GITHUB_TOKEN }}
-          script: |
-            const fs = require('fs');
-            const pytest_logs = fs.readFileSync('pytest-logs.txt', 'utf8');
-            const title = "⚠️ Nightly upstream-dev CI failed ⚠️"
-            const workflow_url = `https://github.com/${process.env.GITHUB_REPOSITORY}/actions/runs/${process.env.GITHUB_RUN_ID}`
-            const issue_body = `[Workflow Run URL](${workflow_url})\n${pytest_logs}`
-
-            // Run GraphQL query against GitHub API to find the most recent open issue used for reporting failures
-            const query = `query($owner:String!, $name:String!, $creator:String!, $label:String!){
-              repository(owner: $owner, name: $name) {
-                issues(first: 1, states: OPEN, filterBy: {createdBy: $creator, labels: [$label]}, orderBy: {field: CREATED_AT, direction: DESC}) {
-                  edges {
-                    node {
-                      body
-                      id
-                      number
-                    }
-                  }
-                }
-              }
-            }`;
-
-            const variables = {
-                owner: context.repo.owner,
-                name: context.repo.repo,
-                label: 'CI',
-                creator: "github-actions[bot]"
-            }
-            const result = await github.graphql(query, variables)
-
-            // If no issue is open, create a new issue,
-            // else update the body of the existing issue.
-            if (result.repository.issues.edges.length === 0) {
-                github.rest.issues.create({
-                    owner: variables.owner,
-                    repo: variables.name,
-                    body: issue_body,
-                    title: title,
-                    labels: [variables.label]
-                })
-            } else {
-                github.rest.issues.update({
-                    owner: variables.owner,
-                    repo: variables.name,
-                    issue_number: result.repository.issues.edges[0].node.number,
-                    body: issue_body
-                })
-            }
+          log-path: output-${{ matrix.python-version }}-log.jsonl

.pre-commit-config.yaml

@@ -10,7 +10,7 @@ repos:
       - id: mixed-line-ending
     # This wants to go before isort & flake8
   - repo: https://github.com/PyCQA/autoflake
-    rev: "v1.7.6"
+    rev: "v1.7.7"
     hooks:
       - id: autoflake # isort should run before black as black sometimes tweaks the isort output
         args: ["--in-place", "--ignore-init-module-imports"]

doc/user-guide/computation.rst

@@ -360,14 +360,14 @@ and ``mean``, ``std`` and ``var`` return ``NaN``:
   ``weights`` must be a :py:class:`DataArray` and cannot contain missing values.
   Missing values can be replaced manually by ``weights.fillna(0)``.
 
-.. _comput.coarsen:
+.. _compute.coarsen:
 
 Coarsen large arrays
 ====================
 
 :py:class:`DataArray` and :py:class:`Dataset` objects include a
 :py:meth:`~xarray.DataArray.coarsen` and :py:meth:`~xarray.Dataset.coarsen`
-methods. This supports the block aggregation along multiple dimensions,
+methods. This supports block aggregation along multiple dimensions,
 
 .. ipython:: python
 
@@ -403,6 +403,7 @@ function or method name to ``coord_func`` option,
 
     da.coarsen(time=7, x=2, coord_func={"time": "min"}).mean()
 
+You can also :ref:`use coarsen to reshape<reshape.coarsen>` without applying a computation.
 
 .. _compute.using_coordinates:
 

doc/user-guide/plotting.rst

@@ -156,18 +156,18 @@ Keyword arguments work the same way, and are more explicit.
 
 To add the plot to an existing axis pass in the axis as a keyword argument
 ``ax``. This works for all xarray plotting methods.
-In this example ``axes`` is an array consisting of the left and right
+In this example ``axs`` is an array consisting of the left and right
 axes created by ``plt.subplots``.
 
 .. ipython:: python
     :okwarning:
 
-    fig, axes = plt.subplots(ncols=2)
+    fig, axs = plt.subplots(ncols=2)
 
-    axes
+    axs
 
-    air1d.plot(ax=axes[0])
-    air1d.plot.hist(ax=axes[1])
+    air1d.plot(ax=axs[0])
+    air1d.plot.hist(ax=axs[1])
 
     plt.tight_layout()
 
@@ -348,8 +348,8 @@ The keyword arguments ``xincrease`` and ``yincrease`` let you control the axes d
 
 In addition, one can use ``xscale, yscale`` to set axes scaling;
 ``xticks, yticks`` to set axes ticks and ``xlim, ylim`` to set axes limits.
-These accept the same values as the matplotlib methods ``Axes.set_(x,y)scale()``,
-``Axes.set_(x,y)ticks()``, ``Axes.set_(x,y)lim()`` respectively.
+These accept the same values as the matplotlib methods ``ax.set_(x,y)scale()``,
+``ax.set_(x,y)ticks()``, ``ax.set_(x,y)lim()``, respectively.
 
 
 Two Dimensions
@@ -701,12 +701,12 @@ that links a :py:class:`DataArray` to a matplotlib figure with a particular stru
 This object can be used to control the behavior of the multiple plots.
 It borrows an API and code from `Seaborn's FacetGrid
 <https://seaborn.pydata.org/tutorial/axis_grids.html>`_.
-The structure is contained within the ``axes`` and ``name_dicts``
+The structure is contained within the ``axs`` and ``name_dicts``
 attributes, both 2d NumPy object arrays.
 
 .. ipython:: python
 
-    g.axes
+    g.axs
 
     g.name_dicts
 
@@ -726,10 +726,10 @@ they have been plotted.
 
     g = t.plot.imshow(x="lon", y="lat", col="time", col_wrap=3, robust=True)
 
-    for i, ax in enumerate(g.axes.flat):
+    for i, ax in enumerate(g.axs.flat):
         ax.set_title("Air Temperature %d" % i)
 
-    bottomright = g.axes[-1, -1]
+    bottomright = g.axs[-1, -1]
     bottomright.annotate("bottom right", (240, 40))
 
     @savefig plot_facet_iterator.png
@@ -928,7 +928,7 @@ by faceting are accessible in the object returned by ``plot``:
         col="time",
         subplot_kws={"projection": ccrs.Orthographic(-80, 35)},
     )
-    for ax in p.axes.flat:
+    for ax in p.axs.flat:
         ax.coastlines()
         ax.gridlines()
     @savefig plotting_maps_cartopy_facetting.png width=100%
@@ -958,11 +958,11 @@ These are provided for user convenience; they all call the same code.
     import xarray.plot as xplt
 
     da = xr.DataArray(range(5))
-    fig, axes = plt.subplots(ncols=2, nrows=2)
-    da.plot(ax=axes[0, 0])
-    da.plot.line(ax=axes[0, 1])
-    xplt.plot(da, ax=axes[1, 0])
-    xplt.line(da, ax=axes[1, 1])
+    fig, axs = plt.subplots(ncols=2, nrows=2)
+    da.plot(ax=axs[0, 0])
+    da.plot.line(ax=axs[0, 1])
+    xplt.plot(da, ax=axs[1, 0])
+    xplt.line(da, ax=axs[1, 1])
     plt.tight_layout()
     @savefig plotting_ways_to_use.png width=6in
     plt.draw()

doc/user-guide/reshaping.rst

@@ -4,7 +4,7 @@
 Reshaping and reorganizing data
 ###############################
 
-These methods allow you to reorganize
+These methods allow you to reorganize your data by changing dimensions, array shape, order of values, or indexes.
 
 .. ipython:: python
     :suppress:
@@ -292,3 +292,54 @@ As a shortcut, you can refer to existing coordinates by name:
     ds.sortby("x")
     ds.sortby(["y", "x"])
     ds.sortby(["y", "x"], ascending=False)
+
+.. _reshape.coarsen:
+
+Reshaping via coarsen
+---------------------
+
+Whilst :py:class:`~xarray.DataArray.coarsen` is normally used for reducing your data's resolution by applying a reduction function
+(see the :ref:`page on computation<compute.coarsen>`),
+it can also be used to reorganise your data without applying a computation via :py:meth:`~xarray.core.rolling.DataArrayCoarsen.construct`.
+
+Taking our example tutorial air temperature dataset over the Northern US
+
+.. ipython:: python
+    :suppress:
+
+    # Use defaults so we don't get gridlines in generated docs
+    import matplotlib as mpl
+
+    mpl.rcdefaults()
+
+.. ipython:: python
+
+    air = xr.tutorial.open_dataset("air_temperature")["air"]
+
+    @savefig pre_coarsening.png
+    air.isel(time=0).plot(x="lon", y="lat")
+
+we can split this up into sub-regions of size ``(9, 18)`` points using :py:meth:`~xarray.core.rolling.DataArrayCoarsen.construct`:
+
+.. ipython:: python
+
+    regions = air.coarsen(lat=9, lon=18, boundary="pad").construct(
+        lon=("x_coarse", "x_fine"), lat=("y_coarse", "y_fine")
+    )
+    regions
+
+9 new regions have been created, each of size 9 by 18 points.
+The ``boundary="pad"`` kwarg ensured that all regions are the same size even though the data does not evenly divide into these sizes.
+
+By plotting these 9 regions together via :ref:`faceting<plotting.faceting>` we can see how they relate to the original data.
+
+.. ipython:: python
+
+    @savefig post_coarsening.png
+    regions.isel(time=0).plot(
+        x="x_fine", y="y_fine", col="x_coarse", row="y_coarse", yincrease=False
+    )
+
+We are now free to easily apply any custom computation to each coarsened region of our new dataarray.
+This would involve specifying that applied functions should act over the ``"x_fine"`` and ``"y_fine"`` dimensions,
+but broadcast over the ``"x_coarse"`` and ``"y_coarse"`` dimensions.

doc/whats-new.rst

@@ -25,6 +25,9 @@ New Features
 
 - Add static typing to plot accessors (:issue:`6949`, :pull:`7052`).
   By `Michael Niklas <https://github.com/headtr1ck>`_.
+- Display the indexes in a new section of the text and HTML reprs
+  (:pull:`6795`, :pull:`7183`, :pull:`7185`)
+  By `Justus Magin <https://github.com/keewis>`_ and `Benoît Bovy <https://github.com/benbovy>`_.
 
 Breaking changes
 ~~~~~~~~~~~~~~~~
@@ -39,6 +42,10 @@ Deprecations
 
 - Positional arguments for all plot methods have been deprecated (:issue:`6949`, :pull:`7052`).
   By `Michael Niklas <https://github.com/headtr1ck>`_.
+- ``xarray.plot.FacetGrid.axes`` has been renamed to ``xarray.plot.FacetGrid.axs``
+  because it's not clear if ``axes`` refers to single or multiple ``Axes`` instances.
+  This aligns with ``matplotlib.pyplot.subplots``. (:pull:`7194`)
+  By `Jimmy Westling <https://github.com/illviljan>`_.
 
 Bug fixes
 ~~~~~~~~~
@@ -55,7 +62,10 @@ Documentation
   Add :py:meth:`__str__` to surface the new :py:class:`BackendEntrypoint` ``description``
   and ``url`` attributes. (:issue:`6577`, :pull:`7000`)
   By `Jessica Scheick <https://github.com/jessicas11>`_.
-
+- Add example of using :py:meth:`DataArray.coarsen.construct` to User Guide. (:pull:`7192`)
+  By `Tom Nicholas <https://github.com/TomNicholas>`_.
+- Rename ``axes`` to ``axs`` in plotting to align with ``matplotlib.pyplot.subplots``. (:pull:`7194`)
+  By `Jimmy Westling <https://github.com/illviljan>`_.
 
 Internal Changes
 ~~~~~~~~~~~~~~~~
@@ -2992,7 +3002,7 @@ Highlights include:
 - Removed support for Python 2. This is the first version of xarray that is
   Python 3 only!
 - New :py:meth:`~xarray.DataArray.coarsen` and
-  :py:meth:`~xarray.DataArray.integrate` methods. See :ref:`comput.coarsen`
+  :py:meth:`~xarray.DataArray.integrate` methods. See :ref:`compute.coarsen`
   and :ref:`compute.using_coordinates` for details.
 - Many improvements to cftime support. See below for details.
 
@@ -3048,7 +3058,7 @@ Other enhancements
   By `Ryan Abernathey <https://github.com/rabernat>`_
 - :py:meth:`DataArray.coarsen` and
   :py:meth:`Dataset.coarsen` are newly added.
-  See :ref:`comput.coarsen` for details.
+  See :ref:`compute.coarsen` for details.
   (:issue:`2525`)
   By `Keisuke Fujii <https://github.com/fujiisoup>`_.
 - Upsampling an array via interpolation with resample is now dask-compatible,