GMTDataArrayAccessor: Improve the documentation

Author: seisman

pygmt/xarray/accessor.py

@@ -17,17 +17,35 @@ class GMTDataArrayAccessor:
     GMT accessor for :class:`xarray.DataArray`.
 
     The *gmt* accessor extends :class:`xarray.DataArray` to store GMT-specific
-    properties for grids, which are important for PyGMT to correctly process and plot
-    the grids. The *gmt* accessor contains the following properties:
+    properties for grids and images, which are important for PyGMT to correctly process
+    and plot them. The *gmt* accessor contains the following properties:
 
     - ``registration``: Grid registration type :class:`pygmt.enums.GridRegistration`.
     - ``gtype``: Grid coordinate system type :class:`pygmt.enums.GridType`.
 
+    Notes
+    -----
+    When accessed the first time, the GMT accessor will be first initialized to the
+    default values (``GridRegistration.GRIDLINE`` and ``GridType.CARTESIAN``, i.e., a
+    gridline-registered, Cartesian grid), and then the properties will be updated with
+    the correct grid registration and type determined from the source encoding (i.e.,
+    ``grid.encoding["source"]``), if it is available.
+
+    Due to the limitations of xarray accessors, the GMT accessor is created once per
+    :class:`xarray.DataArray` instance. Thus, the GMT accessor will be re-initialized in
+    cases where the :class:`xarray.DataArray` is manipulated (e.g., arithmetic and slice
+    operations) or when accessing a :class:`xarray.DataArray` from a
+    :class:`xarray.Dataset`. In these cases, the GMT-specific properties will result in
+    incorrect values if the source encoding is dropped or not found, and users need to
+    manually set these properties again.
+
     Examples
     --------
-    For GMT's built-in remote datasets, these GMT-specific properties are automatically
-    determined and you can access them as follows:
+    For grids loaded from a file (e.g., via :func:`xarray.load_dataarray`) and GMT's
+    built-in remote datasets, the GMT-specific properties are automatically determined
+    and you can access them as follows:
 
+    >>> from pathlib import Path
     >>> from pygmt.datasets import load_earth_relief
     >>> # Use the global Earth relief grid with 1 degree spacing
     >>> grid = load_earth_relief(resolution="01d", registration="pixel")
@@ -37,11 +55,54 @@ class GMTDataArrayAccessor:
     >>> # See if grid is in Cartesian or Geographic coordinate system
     >>> grid.gmt.gtype
     <GridType.GEOGRAPHIC: 1>
+    >>> grid.encoding["source"] is not None
+    True
+
+    Inplace assignment operators like ``*=`` don't create new instances, so the
+    properties are still kept:
+
+    >>> grid *= 2.0
+    >>> grid.gmt.registration
+    <GridRegistration.PIXEL: 1>
+    >>> grid.gmt.gtype
+    <GridType.GEOGRAPHIC: 1>
+
+    Slice operation creates a new instance, but the source encoding is kept, so the
+    properties are still kept:
+
+    >>> grid_slice = grid[0:30, 50:80]
+    >>> # grid source encoding is kept in slice operation
+    >>> grid_slice.encoding["source"] is not None
+    True
+    >>> # properties are still kept
+    >>> grid_slice.gmt.registration
+    <GridRegistration.PIXEL: 1>
+    >>> grid_slice.gmt.gtype
+    <GridType.GEOGRAPHIC: 1>
 
-    For :class:`xarray.DataArray` grids created by yourself, ``registration`` and
-    ``gtype`` default to ``GridRegistration.GRIDLINE`` and ``GridType.CARTESIAN`` (i.e.,
-    a gridline-registered, Cartesian grid). You need to set the correct properties
-    before passing it to PyGMT functions:
+    Other grid operations (e.g., arithmetic operations) create new instances and drops
+    the source encoding, so the properties will be reset to the default values:
+
+    >>> grid2 = grid * 2.0
+    >>> # grid source encoding is dropped in arithmetic operation.
+    >>> "source" in grid2.encoding
+    False
+    >>> # properties are reset to the default values
+    >>> grid2.gmt.registration
+    <GridRegistration.GRIDLINE: 0>
+    >>> grid2.gmt.gtype
+    <GridType.CARTESIAN: 0>
+    >>> # Need to set these properties before passing the grid to PyGMT
+    >>> grid2.gmt.registration = grid.gmt.registration
+    >>> grid2.gmt.gtype = grid.gmt.gtype
+    >>> grid2.gmt.registration
+    <GridRegistration.PIXEL: 1>
+    >>> grid2.gmt.gtype
+    <GridType.GEOGRAPHIC: 1>
+
+    For :class:`xarray.DataArray` grids created from scratch, the source encoding is not
+    available, so the properties will be set to the default values, and you need to
+    manually set the correct properties before passing it to PyGMT functions:
 
     >>> import numpy as np
     >>> import xarray as xr
@@ -67,44 +128,10 @@ class GMTDataArrayAccessor:
     >>> grid.gmt.gtype
     <GridType.GEOGRAPHIC: 1>
 
-    Notes
-    -----
-    Due to the limitations of xarray accessors, the GMT accessors are created once per
-    :class:`xarray.DataArray` instance. You may lose these GMT-specific properties when
-    manipulating grids (e.g., arithmetic and slice operations) or when accessing a
-    :class:`xarray.DataArray` from a :class:`xarray.Dataset`. In these cases, you need
-    to manually set these properties before passing the grid to PyGMT.
-
-    Inplace assignment operators like ``*=`` don't create new instances, so the
-    properties are still kept:
-
-    >>> grid *= 2.0
-    >>> grid.gmt.registration
-    <GridRegistration.GRIDLINE: 0>
-    >>> grid.gmt.gtype
-    <GridType.GEOGRAPHIC: 1>
-
-    Other grid operations (e.g., arithmetic or slice operations) create new instances,
-    so the properties will be lost:
-
-    >>> # grid2 is a slice of the original grid
-    >>> grid2 = grid[0:30, 50:80]
-    >>> # Properties are reset to the default values for new instance
-    >>> grid2.gmt.registration
-    <GridRegistration.GRIDLINE: 0>
-    >>> grid2.gmt.gtype
-    <GridType.CARTESIAN: 0>
-    >>> # Need to set these properties before passing the grid to PyGMT
-    >>> grid2.gmt.registration = grid.gmt.registration
-    >>> grid2.gmt.gtype = grid.gmt.gtype
-    >>> grid2.gmt.registration
-    <GridRegistration.GRIDLINE: 0>
-    >>> grid2.gmt.gtype
-    <GridType.GEOGRAPHIC: 1>
-
     Accessing a :class:`xarray.DataArray` from a :class:`xarray.Dataset` always creates
-    new instances, so these properties are always lost. The workaround is to assign the
-    :class:`xarray.DataArray` into a variable:
+    new instances, so these properties are always lost if the source encoding is not
+    available. The workaround is to assign the :class:`xarray.DataArray` into a
+    variable:
 
     >>> ds = xr.Dataset({"zval": grid})
     >>> ds.zval.gmt.registration