Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve docstring for rolling_window #458

Draft
wants to merge 3 commits into
base: main
Choose a base branch
from
Draft

Improve docstring for rolling_window #458

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
41b0b00
Improve docstring of ``rolling_window``
santisoler Jul 1, 2024
288ec90
Add sub headings to examples
santisoler Jul 1, 2024
f3c042d
Merge branch 'main' into rolling-window-docs
santisoler Sep 5, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
97 changes: 80 additions & 17 deletions verde/coordinates.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -951,13 +951,13 @@ def rolling_window(
Select points on a rolling (moving) window.

A window of the given size is moved across the region at a given step
(specified by *spacing* or *shape*). Returns the indices of points falling
inside each window step. You can use the indices to select points falling
inside a given window.
(specified by ``spacing`` or ``shape``). Returns the indices of points
falling inside each window step. You can use the indices to select points
falling inside a given window.

The size of the step when moving the windows can be specified by the
*spacing* parameter. Alternatively, the number of windows in the
South-North and West-East directions can be specified using the *shape*
The length of the step when moving the windows can be specified by the
``spacing`` parameter. Alternatively, the number of windows in the
South-North and West-East directions can be specified using the ``shape``
parameter. **One of the two must be given.**

Parameters
Expand All @@ -967,21 +967,23 @@ def rolling_window(
following order: (easting, northing, vertical, ...). Only easting and
northing will be used, all subsequent coordinates will be ignored.
size : float
The size of the windows. Units should match the units of *coordinates*.
The size of the windows. Units should match the units of
``coordinates``.
spacing : float, tuple = (s_north, s_east), or None
The window size in the South-North and West-East directions,
respectively. A single value means that the size is equal in both
directions.
The distance between the center of neighboring windows in the
South-North and West-East directions, respectively. A single value
means that the size is equal in both directions. Units should match the
units of ``coordinates``.
shape : tuple = (n_north, n_east) or None
The number of blocks in the South-North and West-East directions,
The number of windows in the South-North and West-East directions,
respectively.
region : list = [W, E, S, N]
The boundaries of a given region in Cartesian or geographic
coordinates. If not region is given, will use the bounding region of
the given points.
adjust : {'spacing', 'region'}
Whether to adjust the spacing or the region if required. Ignored if
*shape* is given instead of *spacing*. Defaults to adjusting the
``shape`` is given instead of ``spacing``. Defaults to adjusting the
spacing.

Returns
Expand All @@ -990,11 +992,12 @@ def rolling_window(
Coordinate arrays for the center of each window.
indices : array
Each element of the array corresponds the indices of points falling
inside a window. The array will have the same shape as the
*window_coordinates*. Use the array elements to index the coordinates
for each window. The indices will depend on the number of dimensions in
the input coordinates. For example, if the coordinates are 2D arrays,
each window will contain indices for 2 dimensions (row, column).
inside a window. The array will have the same shape as each of the ones
in ``window_coordinates``. Use the array elements to index the
coordinates for each window. The indices will depend on the number of
dimensions in the input coordinates. For example, if the coordinates
are 2D arrays, each window will contain indices for 2 dimensions (row,
column).

See also
--------
Expand All @@ -1004,6 +1007,57 @@ def rolling_window(
Examples
--------

Scatter points
~~~~~~~~~~~~~~

Generate a set of scatter coordinates:

>>> from verde import scatter_points
>>> region = (-5, -1, 6, 10)
>>> coords = scatter_points(region, size=10, random_state=42)
>>> easting, northing = coords
>>> print(easting)
[-3.5 -1.2 -2.07 -2.61 -4.38 -4.38 -4.77 -1.54 -2.6 -2.17]
>>> print(northing)
[6.08 9.88 9.33 6.85 6.73 6.73 7.22 8.1 7.73 7.16]

Get the rolling window indices by defining rolling windows of 2 meters per
side. Use a separation of 1 meter so they have 50% overlap between
neighboring windows:

>>> window_coords, indices = rolling_window(
... coords, region=region, size=2, spacing=1
... )

Each array in ``window_coords`` will be a 2D array, with the coordinates of
the center of each window.

>>> easting_window, northing_window = window_coords
>>> print(easting_window)
[[-4. -3. -2.]
[-4. -3. -2.]
[-4. -3. -2.]]
>>> print(northing_window)
[[7. 7. 7.]
[8. 8. 8.]
[9. 9. 9.]]

The ``indices`` will also be a 2D array:

>>> print(indices.shape)
(3, 3)

If we want to get the coordinates of the points that fall in the South-West
corner (the first one), we can do so with:

>>> print(easting[indices[0, 0]])
[-3.5 -4.38 -4.38 -4.77]
>>> print(northing[indices[0, 0]])
[6.08 6.73 6.73 7.22]

Gridded coordinates
~~~~~~~~~~~~~~~~~~~

Generate a set of sample coordinates on a grid and determine the indices
of points for each rolling window:

Expand Down Expand Up @@ -1065,6 +1119,9 @@ def rolling_window(
>>> print(coords[1][indices[0, 0]])
[6. 6. 6. 7. 7. 7. 8. 8. 8.]

Shape of ``indices``
~~~~~~~~~~~~~~~~~~~~

If the coordinates are 1D, the indices will also be 1D:

>>> coords1d = [coord.ravel() for coord in coords]
Expand All @@ -1085,6 +1142,9 @@ def rolling_window(
>>> print(coords1d[1][indices[0, 0]])
[6. 6. 6. 7. 7. 7. 8. 8. 8.]

Use ``region`` argument
~~~~~~~~~~~~~~~~~~~~~~~

By default, the windows will span the entire data region. You can also
control the specific region you'd like the windows to cover:

Expand All @@ -1107,6 +1167,9 @@ def rolling_window(
>>> print(coords[1][indices[0, 0]])
[6. 6. 6. 7. 7. 7. 8. 8. 8.]

Passing extra coordinates
~~~~~~~~~~~~~~~~~~~~~~~~~

Only the first 2 coordinates are considered (assumed to be the horizontal
ones). All others will be ignored by the function.

Expand Down
Loading