Skip to content

Commit

Permalink
Updates docstrings
Browse files Browse the repository at this point in the history
  • Loading branch information
@jasonb5
jasonb5 committed Aug 18, 2023
1 parent 5a57b7c commit 70f2af4
Show file tree
Hide file tree
Showing 4 changed files with 111 additions and 212 deletions.
129 changes: 69 additions & 60 deletions xcdat/regridder/accessor.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23,19 +23,19 @@
@xr.register_dataset_accessor(name="regridder")
class RegridderAccessor:
"""
An accessor class that provides regridding attributes and methods on xarray
Datasets through the ``.regridder`` attribute.
An accessor class that provides regridding attributes and methods for
xarray Datasets through the ``.regridder`` attribute.
Examples
--------
Import RegridderAccessor class:
Import xCDAT:
>>> import xcdat # or from xcdat import regridder
>>> import xcdat
Use RegridderAccessor class:
>>> ds = xcdat.open_dataset("/path/to/file")
>>> ds = xcdat.open_dataset("...")
>>>
>>> ds.regridder.<attribute>
>>> ds.regridder.<method>
Expand All @@ -44,7 +44,7 @@ class RegridderAccessor:
Parameters
----------
dataset : xr.Dataset
A Dataset object.
The Dataset to attach this accessor.
"""

def __init__(self, dataset: xr.Dataset):
Expand All @@ -53,19 +53,35 @@ def __init__(self, dataset: xr.Dataset):
@property
def grid(self) -> xr.Dataset:
"""
Returns ``xr.Dataset`` containing grid information.
Extract the `X`, `Y`, and `Z` axes from the Dataset and return a new
``xr.Dataset``.
Returns
-------
xr.Dataset
With data variables describing the grid.
Containing grid axes.
Raises
------
ValueError
If axis dimension coordinate variable is not correctly identified.
ValueError
If axis has multiple dimensions (only one is expected).
Examples
--------
Import xCDAT:
>>> import xcdat
Open a dataset:
>>> ds = xcdat.open_dataset("...")
Extract grid from dataset:
>>> grid = ds.regridder.grid
"""
with xr.set_options(keep_attrs=True):
coords = {}
Expand Down Expand Up @@ -107,6 +123,7 @@ def _get_axis_data(

return coord_var, bounds_var

# TODO Either provide generic `horizontal` and `vertical` methods or tool specific
def horizontal_xesmf(
self,
data_var: str,
Expand Down Expand Up @@ -168,6 +185,7 @@ def horizontal_xesmf(
"in your conda environment."
)

# TODO Either provide generic `horizontal` and `vertical` methods or tool specific
def horizontal_regrid2(
self,
data_var: str,
Expand Down Expand Up @@ -223,8 +241,7 @@ def horizontal(
**options: Dict[str, Any],
) -> xr.Dataset:
"""
Apply horizontal regridding to ``data_var`` of the current
``xr.Dataset`` to ``output_grid``.
Transform ``data_var`` to ``output_grid``.
When might ``Regrid2`` be preferred over ``xESMF``?
Expand All @@ -236,44 +253,30 @@ def horizontal(
Supported tools, methods and grids:
- xESMF (https://pangeo-xesmf.readthedocs.io/en/latest/)
- Methods:
- Bilinear
- Conservative
- Conservative Normed
- Patch
- Nearest s2d
- Nearest d2s
- Grids:
- Rectilinear
- Curvilinear
- Methods: Bilinear, Conservative, Conservative Normed, Patch, Nearest s2d, or Nearest d2s.
- Grids: Rectilinear, or Curvilinear.
- Find options at :py:func:`xcdat.regridder.xesmf.XESMFRegridder`
- Regrid2
- Methods:
- Conservative
- Grids:
- Rectilinear
- Methods: Conservative
- Grids: Rectilinear
- Find options at :py:func:`xcdat.regridder.regrid2.Regrid2Regridder`
Parameters
----------
data_var: str
Name of the variable in the ``xr.Dataset`` to regrid.
Name of the variable to transform.
output_grid : xr.Dataset
Dataset containing output grid.
Grid to transform ``data_var`` to.
tool : str
Name of the regridding tool.
**options : Dict[str, Any]
These options are passed to the tool being used for regridding.
See specific regridder documentation for available options.
Name of the tool to use.
**options : Any
These options are passed directly to the ``tool``. See specific
regridder for available options.
Returns
-------
xr.Dataset
With the ``data_var`` variable on the grid defined in ``output_grid``.
With the ``data_var`` transformed to the ``output_grid``.
Raises
------
Expand All @@ -287,23 +290,25 @@ def horizontal(
Examples
--------
Create destination grid:
Import xCDAT:
>>> output_grid = xcdat.create_uniform_grid(-90, 90, 4.0, -180, 180, 5.0)
>>> import xcdat
Regrid variable using "xesmf":
Open a dataset:
>>> ds.regridder.horizontal("ts", output_grid, tool="xesmf", method="bilinear")
>>> ds = xcdat.open_dataset("...")
Regrid variable using "regrid2":
Create output grid:
>>> ds.regridder.horizontal("ts", output_grid, tool="regrid2")
>>> output_grid = xcdat.create_uniform_grid(-90, 90, 4.0, -180, 180, 5.0)
Use convenience methods:
Regrid variable using "xesmf":
>>> ds.regridder.horizontal_xesmf("ts", output_grid, method="bilinear")
>>> output_data = ds.regridder.horizontal("ts", output_grid, tool="xesmf", method="bilinear")
>>> ds.regridder.horizontal_regrid2("ts", output_grid)
Regrid variable using "regrid2":
>>> output_data = ds.regridder.horizontal("ts", output_grid, tool="regrid2")
"""
# TODO: Test this conditional.
if tool == "xesmf" and not _has_xesmf: # pragma: no cover
Expand Down Expand Up @@ -333,35 +338,30 @@ def vertical(
**options: Any,
) -> xr.Dataset:
"""
Apply vertical regridding to ``data_var`` of the current ``xr.Dataset``
to ``output_grid``.
Transform ``data_var`` to ``output_grid``.
Supported tools:
- xgcm (https://xgcm.readthedocs.io/en/latest/index.html)
- Methods:
- Linear
- Conservative
- Log
- Methods: Linear, Conservative, Log
- Find options at :py:func:`xcdat.regridder.xgcm.XGCMRegridder`
Parameters
----------
data_var: str
Name of the variable in the ``xr.Dataset`` to regrid.
Name of the variable to transform.
output_grid : xr.Dataset
Dataset containing output grid.
Grid to transform ``data_var`` to.
tool : str
Name of the regridding tool.
**options : Dict[str, Any]
These options are passed to the tool being used for regridding.
See specific regridder documentation for available options.
Name of the tool to use.
**options : Any
These options are passed directly to the ``tool``. See specific
regridder for available options.
Returns
-------
xr.Dataset
With the ``data_var`` variable on the grid defined in ``output_grid``.
With the ``data_var`` transformed to the ``output_grid``.
Raises
------
Expand All @@ -370,13 +370,22 @@ def vertical(
Examples
--------
Create destination grid:
Import xCDAT:
>>> import xcdat
Open a dataset:
>>> ds = xcdat.open_dataset("...")
Create output grid:
>>> output_grid = xcdat.create_grid(lev=np.linspace(1000, 1, 20))
Regrid variable using "xgcm":
>>> ds.regridder.vertical("so", output_grid, method="linear")
>>> output_data = ds.regridder.vertical("so", output_grid, method="linear")
"""
try:
regrid_tool = VERTICAL_REGRID_TOOLS[tool]
Expand Down
51 changes: 5 additions & 46 deletions xcdat/regridder/regrid2.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -24,31 +24,27 @@ def __init__(
Dataset containing the source grid.
output_grid : xr.Dataset
Dataset containing the destination grid.
options : Dict[str, Any]
options : Any
Dictionary with extra parameters for the regridder.
Examples
--------
Import xCDAT:
>>> import xcdat
>>> from xcdat.regridder import regrid2
Open a dataset:
>>> ds = xcdat.open_dataset("ts.nc")
>>> ds = xcdat.open_dataset("...")
Create output grid:
>>> output_grid = xcdat.create_gaussian_grid(32)
Create regridder:
>>> regridder = regrid2.Regrid2Regridder(ds.regridder.grid, output_grid)
Regrid data:
>>> data_new_grid = regridder.horizontal("ts", ds)
>>> output_data = ds.regridder.horizontal("ts", output_grid)
"""
super().__init__(input_grid, output_grid, **options)

Expand All @@ -69,44 +65,7 @@ def vertical(self, data_var: str, ds: xr.Dataset) -> xr.Dataset:
raise NotImplementedError()

def horizontal(self, data_var: str, ds: xr.Dataset) -> xr.Dataset:
"""Regrid ``data_var`` in ``ds`` to output grid.
Mappings and weights between input and output grid are calculated
on the first call, allowing a regridder to be applied to many input
datasets.
Parameters
----------
data_var : str
The name of the data variable inside the dataset to regrid.
ds : xr.Dataset
The dataset containing ``data_var``.
Returns
-------
xr.Dataset
Dataset with variable on the destination grid.
Raises
------
KeyError
If data variable does not exist in the Dataset.
Examples
--------
Create output grid:
>>> output_grid = xcdat.create_gaussian_grid(32)
Create regridder:
>>> regridder = regrid2.Regrid2Regridder(ds, output_grid)
Regrid data:
>>> data_new_grid = regridder.horizontal("ts", ds)
"""
"""See documentation in :py:func:`xcdat.regridder.regrid2.Regrid2Regridder`"""
input_data_var = ds.get(data_var, None)

if input_data_var is None:
Expand Down
Loading

0 comments on commit 70f2af4

Please sign in to comment.