From c17bc35a809e27f09731dff8c08238e64f6f77d0 Mon Sep 17 00:00:00 2001 From: "Alan D. Snow" Date: Thu, 21 Jul 2022 17:52:22 -0500 Subject: [PATCH] DOC: Add intersphinx for matplotlib & numpy (#2527) --- docs/conf.py | 2 ++ docs/quickstart.rst | 2 +- docs/topics/masks.rst | 8 ++++---- docs/topics/migrating-to-v1.rst | 2 +- docs/topics/plotting.rst | 2 +- docs/topics/reading.rst | 2 +- docs/topics/switch.rst | 4 ++-- rasterio/__init__.py | 9 ++++----- rasterio/_features.pyx | 8 ++++---- rasterio/_io.pyx | 18 +++++++++--------- rasterio/_warp.pyx | 6 +++--- rasterio/dtypes.py | 2 +- rasterio/features.py | 26 +++++++++++++------------- rasterio/fill.py | 6 +++--- rasterio/mask.py | 2 +- rasterio/merge.py | 4 ++-- rasterio/plot.py | 21 ++++++++------------- 17 files changed, 60 insertions(+), 64 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 9168945a..cff4cbc8 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -367,4 +367,6 @@ epub_exclude_files = ['search.html'] intersphinx_mapping = { "python": ("https://docs.python.org/", None), "gdal": ("https://gdal.org/", None), + "numpy": ("https://numpy.org/doc/stable", None), + "matplotlib": ("https://matplotlib.org/stable/", None), } diff --git a/docs/quickstart.rst b/docs/quickstart.rst index 6f24934f..d7fca26a 100644 --- a/docs/quickstart.rst +++ b/docs/quickstart.rst @@ -161,7 +161,7 @@ the GDAL convention, bands are indexed from 1. (1,) >>> band1 = dataset.read(1) -The :meth:`~rasterio.io.DatasetReader.read` method returns a Numpy N-D array. +The :meth:`~rasterio.io.DatasetReader.read` method returns a :class:`numpy.ndarray`. .. code-block:: pycon diff --git a/docs/topics/masks.rst b/docs/topics/masks.rst index 9808c884..1ae9fad8 100644 --- a/docs/topics/masks.rst +++ b/docs/topics/masks.rst @@ -9,7 +9,7 @@ rows and columns as the dataset in which non-zero elements (typically 255) indic corresponding data elements are valid. Other elements are invalid, or *nodata* elements. -The other kind of mask is Numpy's `masked array `__ +The other kind of mask is a :class:`numpy.ma.MaskedArray` which has the inverse sense: `True` values in a masked array's mask indicate that the corresponding data elements are invalid. With care, you can safely navigate convert between the two mask types. @@ -78,7 +78,7 @@ array shows the ``255`` values that indicate *valid data* regions. [255, 255, 255, 255, 255], [255, 255, 255, 255, 255]], dtype=uint8) -Displayed using Matplotlib's `imshow()`, the mask looks like this: +Displayed using :func:`matplotlib.pyplot.imshow`, the mask looks like this: .. image:: ../img/mask_band.png @@ -140,7 +140,7 @@ certainly can. Consider a fresh copy of that file. This time we'll read all 3 band masks (based on the nodata values, not a .msk GeoTIFF) and show them -as an RGB image (with the help of `numpy.dstack()`): +as an RGB image (with the help of :func:`numpy.dstack`): .. code-block:: python @@ -185,7 +185,7 @@ considered valid. Numpy masked arrays ------------------- -If you want, you can read dataset bands as numpy masked arrays. +If you want, you can read dataset bands as a :class:`numpy.ma.MaskedArray`. .. code-block:: python diff --git a/docs/topics/migrating-to-v1.rst b/docs/topics/migrating-to-v1.rst index b037ada9..5be676cd 100644 --- a/docs/topics/migrating-to-v1.rst +++ b/docs/topics/migrating-to-v1.rst @@ -127,7 +127,7 @@ Removed: ``src.read_band()`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The ``read_band()`` method has been replaced by ``read()``, which allows for -faster I/O and reading multiple bands into a single ``numpy.ndarray()``. +faster I/O and reading multiple bands into a single :class:`numpy.ndarray`. For example: diff --git a/docs/topics/plotting.rst b/docs/topics/plotting.rst index 72a6ebb6..f5a6de16 100644 --- a/docs/topics/plotting.rst +++ b/docs/topics/plotting.rst @@ -24,7 +24,7 @@ The first argument to :func:`~rasterio.plot.show` represent the data source to b * A dataset object opened in 'r' mode * A single band of a source, represented by a ``(src, band_index)`` tuple - * A numpy ndarray, 2D or 3D. If the array is 3D, ensure that it is in rasterio band order. + * A :class:`numpy.ndarray`, 2D or 3D. If the array is 3D, ensure that it is in rasterio band order. Thus the following operations for 3-band RGB data are equivalent. Note that when passing arrays, you can pass in a transform in order to get extent labels. diff --git a/docs/topics/reading.rst b/docs/topics/reading.rst index 9c7cc9cf..13248938 100644 --- a/docs/topics/reading.rst +++ b/docs/topics/reading.rst @@ -55,7 +55,7 @@ a file can be read like this: >>> array.shape (718, 791) -The returned object is a 2-dimensional Numpy ndarray. The representation of +The returned object is a 2-dimensional :class:`numpy.ndarray`. The representation of that array at the Python prompt is a summary; the GeoTIFF file that Rasterio uses for testing has 0 values in the corners, but has nonzero values elsewhere. diff --git a/docs/topics/switch.rst b/docs/topics/switch.rst index f83ff49d..660b7a72 100644 --- a/docs/topics/switch.rst +++ b/docs/topics/switch.rst @@ -192,7 +192,7 @@ band index and some other band properties. Thus Rasterio never has objects with dangling dataset pointers. With Rasterio, bands are represented by a numerical index, starting from 1 (as GDAL does), and are used as arguments to dataset -methods. To read the first band of a dataset as a Numpy ``ndarray``, do this. +methods. To read the first band of a dataset as a :class:`numpy.ndarray`, do this. .. code-block:: python @@ -349,7 +349,7 @@ data. [0, 0, 0, ..., 0, 0, 0], [0, 0, 0, ..., 0, 0, 0]], dtype-uint8) -Arrays for dataset bands can also be had as a Numpy ``masked_array``. +Arrays for dataset bands can also be had as a :class:`numpy.ma.MaskedArray`. .. code-block:: pycon diff --git a/rasterio/__init__.py b/rasterio/__init__.py index cce18371..a87d6e03 100644 --- a/rasterio/__init__.py +++ b/rasterio/__init__.py @@ -128,9 +128,9 @@ def open(fp, mode='r', driver=None, width=None, height=None, count=None, Affine transformation mapping the pixel space to geographic space. Required in 'w' or 'w+' modes, it is ignored in 'r' or 'r+' modes. - dtype : str or numpy dtype + dtype : str or numpy.dtype The data type for bands. For example: 'uint8' or - ``rasterio.uint16``. Required in 'w' or 'w+' modes, it is + :attr:`rasterio.uint16`. Required in 'w' or 'w+' modes, it is ignored in 'r' or 'r+' modes. nodata : int, float, or nan; optional Defines the pixel value to be interpreted as not valid data. @@ -334,7 +334,7 @@ def pad(array, transform, pad_width, mode=None, **kwargs): Parameters ---------- - array: ndarray + array: numpy.ndarray Numpy ndarray, for best results a 2D array transform: Affine transform transform object mapping pixel space to coordinates @@ -350,8 +350,7 @@ def pad(array, transform, pad_width, mode=None, **kwargs): Notes ----- - See numpy docs for details on mode and other kwargs: - http://docs.scipy.org/doc/numpy-1.10.0/reference/generated/numpy.pad.html + See :func:`numpy.pad` for details on mode and other kwargs. """ import numpy as np transform = guard_transform(transform) diff --git a/rasterio/_features.pyx b/rasterio/_features.pyx index 18793be9..1035f0e6 100644 --- a/rasterio/_features.pyx +++ b/rasterio/_features.pyx @@ -25,7 +25,7 @@ def _shapes(image, mask, connectivity, transform): image : array or dataset object opened in 'r' mode or Band or tuple(dataset, bidx) Data type must be one of rasterio.int16, rasterio.int32, rasterio.uint8, rasterio.uint16, or rasterio.float32. - mask : numpy ndarray or rasterio Band object + mask : numpy.ndarray or rasterio Band object Values of False or 0 will be excluded from feature generation Must evaluate to bool (rasterio.bool_ or rasterio.uint8) connectivity : int @@ -160,9 +160,9 @@ def _sieve(image, size, out, mask, connectivity): rasterio.uint16, or rasterio.float32. size : int minimum polygon size (number of pixels) to retain. - out : numpy ndarray + out : numpy.ndarray Array of same shape and data type as `image` in which to store results. - mask : numpy ndarray or rasterio Band object + mask : numpy.ndarray or rasterio Band object Values of False or 0 will be excluded from feature generation. Must evaluate to bool (rasterio.bool_ or rasterio.uint8) connectivity : int @@ -267,7 +267,7 @@ def _rasterize(shapes, image, transform, all_touched, merge_alg): ---------- shapes : iterable of (geometry, value) pairs `geometry` is a GeoJSON-like object. - image : numpy ndarray + image : numpy.ndarray Array in which to store results. transform : Affine transformation object, optional Transformation from pixel coordinates of `image` to the diff --git a/rasterio/_io.pyx b/rasterio/_io.pyx index 58542d7b..a98b7115 100644 --- a/rasterio/_io.pyx +++ b/rasterio/_io.pyx @@ -318,7 +318,7 @@ cdef bint in_dtype_range(value, dtype): cdef int io_auto(data, GDALRasterBandH band, bint write, int resampling=0) except -1: """Convenience function to handle IO with a GDAL band. - :param data: a numpy ndarray + :param data: a numpy.ndarray :param band: an instance of GDALGetRasterBand :param write: 1 (True) uses write mode (writes data into band), 0 (False) uses read mode (reads band into data) @@ -405,7 +405,7 @@ cdef class DatasetReaderBase(DatasetBase): indexes : int or list, optional If `indexes` is a list, the result is a 3D array, but is a 2D array if it is a band index number. - out : numpy ndarray, optional + out : numpy.ndarray, optional As with Numpy ufuncs, this is an optional reference to an output array into which data will be placed. If the height and width of `out` differ from that of the specified @@ -416,7 +416,7 @@ cdef class DatasetReaderBase(DatasetBase): *Note*: the method's return value may be a view on this array. In other words, `out` is likely to be an incomplete representation of the method's results. - out_dtype : str or numpy dtype + out_dtype : str or numpy.dtype The desired output data type. For example: 'uint8' or rasterio.uint16. out_shape : tuple, optional @@ -442,7 +442,7 @@ cdef class DatasetReaderBase(DatasetBase): are not cached. fill_value : scalar Fill value applied in the `boundless=True` case only. Like - the fill_value of numpy.ma.MaskedArray, should be value + the fill_value of :class:`numpy.ma.MaskedArray`, should be value valid for the dataset's data type. Returns @@ -708,7 +708,7 @@ cdef class DatasetReaderBase(DatasetBase): indexes : int or list, optional If `indexes` is a list, the result is a 3D array, but is a 2D array if it is a band index number. - out : numpy ndarray, optional + out : numpy.ndarray, optional As with Numpy ufuncs, this is an optional reference to an output array into which data will be placed. If the height and width of `out` differ from that of the specified @@ -944,7 +944,7 @@ cdef class DatasetReaderBase(DatasetBase): Parameters ---------- - out : numpy ndarray, optional + out : numpy.ndarray, optional As with Numpy ufuncs, this is an optional reference to an output array with the same dimensions and shape into which data will be placed. @@ -1327,7 +1327,7 @@ cdef class DatasetWriterBase(DatasetReaderBase): Affine transformation mapping the pixel space to geographic space. Required in 'w' or 'w+' modes, it is ignored in 'r' or 'r+' modes. - dtype : str or numpy dtype + dtype : str or numpy.dtype The data type for bands. For example: 'uint8' or ``rasterio.uint16``. Required in 'w' or 'w+' modes, it is ignored in 'r' or 'r+' modes. @@ -1640,7 +1640,7 @@ cdef class DatasetWriterBase(DatasetReaderBase): Parameters ---------- arr : array-like - This may be a numpy MaskedArray. + This may be a :class:`numpy.ma.MaskedArray`. indexes : int or list, optional Which bands of the dataset to write to. The default is all. window : Window, optional @@ -2137,7 +2137,7 @@ cdef class BufferedDatasetWriterBase(DatasetWriterBase): Affine transformation mapping the pixel space to geographic space. Required in 'w' or 'w+' modes, it is ignored in 'r' or 'r+' modes. - dtype : str or numpy dtype + dtype : str or numpy.dtype The data type for bands. For example: 'uint8' or ``rasterio.uint16``. Required in 'w' or 'w+' modes, it is ignored in 'r' or 'r+' modes. diff --git a/rasterio/_warp.pyx b/rasterio/_warp.pyx index f219bda9..e969bc64 100644 --- a/rasterio/_warp.pyx +++ b/rasterio/_warp.pyx @@ -1168,7 +1168,7 @@ cdef class WarpedVRTReaderBase(DatasetReaderBase): If `indexes` is a list, the result is a 3D array, but is a 2D array if it is a band index number. - out : numpy ndarray, optional + out : numpy.ndarray, optional As with Numpy ufuncs, this is an optional reference to an output array into which data will be placed. If the height and width of `out` differ from that of the specified @@ -1182,7 +1182,7 @@ cdef class WarpedVRTReaderBase(DatasetReaderBase): This parameter cannot be combined with `out_shape`. - out_dtype : str or numpy dtype + out_dtype : str or numpy.dtype The desired output data type. For example: 'uint8' or rasterio.uint16. @@ -1222,7 +1222,7 @@ cdef class WarpedVRTReaderBase(DatasetReaderBase): Returns ------- - Numpy ndarray or a view on a Numpy ndarray + numpy.ndarray or a view on a numpy.ndarray Note: as with Numpy ufuncs, an object is returned even if you use the optional `out` argument and the return value shall be diff --git a/rasterio/dtypes.py b/rasterio/dtypes.py index 23e44621..6191e815 100644 --- a/rasterio/dtypes.py +++ b/rasterio/dtypes.py @@ -186,7 +186,7 @@ def can_cast_dtype(values, dtype): Parameters ---------- values: list-like - dtype: numpy dtype or string + dtype: numpy.dtype or string Returns ------- diff --git a/rasterio/features.py b/rasterio/features.py index 6184db70..8541b35c 100644 --- a/rasterio/features.py +++ b/rasterio/features.py @@ -41,7 +41,7 @@ def geometry_mask( ---------- geometries : iterable over geometries (GeoJSON-like objects) out_shape : tuple or list - Shape of output numpy ndarray. + Shape of output :class:`numpy.ndarray`. transform : Affine transformation object Transformation from pixel coordinates of `source` to the coordinate system of the input `shapes`. See the `transform` @@ -56,8 +56,8 @@ def geometry_mask( Returns ------- - numpy ndarray of type 'bool' - Result + numpy.ndarray : + Type is :class:`numpy.bool_` Notes ----- @@ -81,15 +81,15 @@ def shapes(source, mask=None, connectivity=4, transform=IDENTITY): Parameters ---------- - source : array, dataset object, Band, or tuple(dataset, bidx) + source : numpy.ndarray, dataset object, Band, or tuple(dataset, bidx) Data type must be one of rasterio.int16, rasterio.int32, rasterio.uint8, rasterio.uint16, or rasterio.float32. - mask : numpy ndarray or rasterio Band object, optional + mask : numpy.ndarray or rasterio Band object, optional Must evaluate to bool (rasterio.bool_ or rasterio.uint8). Values of False or 0 will be excluded from feature generation. Note well that this is the inverse sense from Numpy's, where a mask value of True indicates invalid data in an array. If `source` is - a Numpy masked array and `mask` is None, the source's mask will + a :class:`numpy.ma.MaskedArray` and `mask` is None, the source's mask will be inverted and used in place of `mask`. connectivity : int, optional Use 4 or 8 pixel connectivity for grouping pixels into features @@ -142,9 +142,9 @@ def sieve(source, size, out=None, mask=None, connectivity=4): rasterio.uint16, or rasterio.float32 size : int minimum polygon size (number of pixels) to retain. - out : numpy ndarray, optional + out : numpy.ndarray, optional Array of same shape and data type as `source` in which to store results. - mask : numpy ndarray or rasterio Band object, optional + mask : numpy.ndarray or rasterio Band object, optional Values of False or 0 will be excluded from feature generation Must evaluate to bool (rasterio.bool_ or rasterio.uint8) connectivity : int, optional @@ -152,7 +152,7 @@ def sieve(source, size, out=None, mask=None, connectivity=4): Returns ------- - out : numpy ndarray + out : numpy.ndarray Result Notes @@ -199,11 +199,11 @@ def rasterize( the `default_value` will be used. If `value` is `None` the `fill` value will be used. out_shape : tuple or list with 2 integers - Shape of output numpy ndarray. + Shape of output :class:`numpy.ndarray`. fill : int or float, optional Used as fill value for all areas not covered by input geometries. - out : numpy ndarray, optional + out : numpy.ndarray, optional Array of same shape and data type as `source` in which to store results. transform : Affine transformation object, optional @@ -222,12 +222,12 @@ def rasterize( the new value will be added to the existing raster. default_value : int or float, optional Used as value for all geometries, if not provided in `shapes`. - dtype : rasterio or numpy data type, optional + dtype : rasterio or numpy.dtype, optional Used as data type for results, if `out` is not provided. Returns ------- - numpy ndarray + numpy.ndarray : If `out` was not None then `out` is returned, it will have been modified in-place. If `out` was None, this will be a new array. diff --git a/rasterio/fill.py b/rasterio/fill.py index 5a759b5f..158383c5 100644 --- a/rasterio/fill.py +++ b/rasterio/fill.py @@ -35,11 +35,11 @@ def fillnodata( Parameters ---------- - image : numpy ndarray + image : numpy.ndarray The source image with holes to be filled. If a MaskedArray, the inverse of its mask will define the pixels to be filled -- unless the ``mask`` argument is not None (see below).` - mask : numpy ndarray or None + mask : numpy.ndarray, optional A mask band indicating which pixels to interpolate. Pixels to interpolate into are indicated by the value 0. Values > 0 indicate areas to use during interpolation. Must be same @@ -55,7 +55,7 @@ def fillnodata( Returns ------- - out : numpy ndarray + numpy.ndarray : The filled raster array. """ if mask is None and isinstance(image, MaskedArray): diff --git a/rasterio/mask.py b/rasterio/mask.py index cc7ce94b..17646b4e 100644 --- a/rasterio/mask.py +++ b/rasterio/mask.py @@ -156,7 +156,7 @@ def mask(dataset, shapes, all_touched=False, invert=False, nodata=None, Two elements: - masked : numpy ndarray or numpy.ma.MaskedArray + masked : numpy.ndarray or numpy.ma.MaskedArray Data contained in the raster after applying the mask. If `filled` is `True` and `invert` is `False`, the return will be an array where pixels outside shapes are set to the nodata value diff --git a/rasterio/merge.py b/rasterio/merge.py index 59918451..f56feaf1 100644 --- a/rasterio/merge.py +++ b/rasterio/merge.py @@ -133,7 +133,7 @@ def merge( nodata: float, optional nodata value to use in output file. If not set, uses the nodata value in the first input raster. - dtype: numpy dtype or string + dtype: numpy.dtype or string dtype to use in outputfile. If not set, uses the dtype value in the first input raster. precision: int, optional @@ -185,7 +185,7 @@ def merge( Two elements: - dest: numpy ndarray + dest: numpy.ndarray Contents of all input rasters in single array out_transform: affine.Affine() diff --git a/rasterio/plot.py b/rasterio/plot.py index c0ea611b..b10155b0 100644 --- a/rasterio/plot.py +++ b/rasterio/plot.py @@ -53,7 +53,7 @@ def show(source, with_bounds=True, contour=False, contour_label_kws=None, contour_label_kws : dictionary (opt) Keyword arguments for labeling the contours, empty dictionary for no labels. - ax : matplotlib axes (opt) + ax : matplotlib.axes.Axes, optional Axes to plot on, otherwise uses current axes. title : str, optional Title for the figure. @@ -65,16 +65,12 @@ def show(source, with_bounds=True, contour=False, contour_label_kws=None, True, values will be adjusted by the min / max of each band. If False, no adjustment will be applied. **kwargs : key, value pairings optional - These will be passed to the matplotlib imshow or contour method - depending on contour argument. - See full lists at: - https://matplotlib.org/stable/api/_as_gen/matplotlib.pyplot.imshow.html - or - https://matplotlib.org/stable/api/_as_gen/matplotlib.pyplot.contour.html + These will be passed to the :func:`matplotlib.pyplot.imshow` or + :func:`matplotlib.pyplot.contour` contour method depending on contour argument. Returns ------- - ax : matplotlib Axes + ax : matplotlib.axes.Axes Axes with plot. """ plt = get_plt() @@ -158,12 +154,12 @@ def show(source, with_bounds=True, contour=False, contour_label_kws=None, def plotting_extent(source, transform=None): """Returns an extent in the format needed - for matplotlib's imshow (left, right, bottom, top) + for :func:`matplotlib.pyplot.imshow` (left, right, bottom, top) instead of rasterio's bounds (left, bottom, right, top) Parameters ---------- - source : array or dataset object opened in 'r' mode + source : numpy.ndarray or dataset object opened in 'r' mode If array, data in the order rows, columns and optionally bands. If array is band order (bands in the first dimension), use arr[0] transform: Affine, required if source is array @@ -238,14 +234,13 @@ def show_hist(source, bins=10, masked=True, title='Histogram', ax=None, label=No should be masked on read. title : str, optional Title for the figure. - ax : matplotlib axes (opt) + ax : matplotlib.axes.Axes, optional The raster will be added to this axes if passed. label : matplotlib labels (opt) If passed, matplotlib will use this label list. Otherwise, a default label list will be automatically created **kwargs : optional keyword arguments - These will be passed to the matplotlib hist method. See full list at: - http://matplotlib.org/api/axes_api.html?highlight=imshow#matplotlib.axes.Axes.hist + These will be passed to the :meth:`matplotlib.axes.Axes.hist` method. """ plt = get_plt()