Skip to content

Commit

Permalink
update docstrings (1)
Browse files Browse the repository at this point in the history
  • Loading branch information
@philipc2
philipc2 committed Nov 15, 2024
1 parent 884ed87 commit 7d5860e
Show file tree
Hide file tree
Showing 3 changed files with 81 additions and 59 deletions.
56 changes: 40 additions & 16 deletions uxarray/cross_sections/dataarray_accessor.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,60 +17,84 @@ def __repr__(self):
prefix = "<uxarray.UxDataArray.cross_section>\n"
methods_heading = "Supported Methods:\n"

methods_heading += " * constant_latitude(center_coord, k, element, **kwargs)\n"
methods_heading += " * constant_latitude(lat, use_spherical_bounding_box)\n"
methods_heading += " * constant_longitude(lon, use_spherical_bounding_box)\n"

return prefix + methods_heading

def constant_latitude(self, lat: float, use_spherical_bounding_box=False):
"""Extracts a cross-section of the data array at a specified constant
latitude.
def constant_latitude(self, lat: float, use_spherical_bounding_box: bool = True):
"""Extracts a cross-section of the data array by selecting all faces that
intersect with a specified line of constant latitude.
Parameters
----------
lat : float
The latitude at which to extract the cross-section, in degrees.
Must be between -90.0 and 90.0
use_spherical_bounding_box : bool, optional
If True, uses a spherical bounding box for intersection calculations.
If True, uses a spherical bounding box for obtaining candidate faces, which considers the extreme cases
along great circle arcs.
Returns
-------
uxarray.UxDataArray
A subset of the original data array containing only the faces that intersect
with the specified latitude.
Raises
------
ValueError
If no intersections are found at the specified latitude, a ValueError is raised.
If no intersections are found at the specified latitude.
Examples
--------
>>> uxda.constant_latitude_cross_section(lat=-15.5)
>>> # Extract data at 15.5°S latitude
>>> cross_section = uxda.constant_latitude(lat=-15.5)
Notes
-----
The initial execution time may be significantly longer than subsequent runs
due to Numba's just-in-time compilation. Subsequent calls will be faster due to caching.
"""
faces = self.uxda.uxgrid.get_faces_at_constant_latitude(
lat, use_spherical_bounding_box
)

return self.uxda.isel(n_face=faces)

def constant_longitude(self, lon: float, use_spherical_bounding_box=False):
"""Extracts a cross-section of the data array at a specified constant
longitude.
def constant_longitude(self, lon: float, use_spherical_bounding_box: bool = True):
"""Extracts a cross-section of the data array by selecting all faces that
intersect with a specified line of constant longitude.
Parameters
----------
lon : float
The longitude at which to extract the cross-section, in degrees.
The latitude at which to extract the cross-section, in degrees.
Must be between -180.0 and 180.0
use_spherical_bounding_box : bool, optional
If True, uses a spherical bounding box for intersection calculations.
If True, uses a spherical bounding box for obtaining candidate faces, which considers the extreme cases
along great circle arcs.
Returns
-------
uxarray.UxDataArray
A subset of the original data array containing only the faces that intersect
with the specified longitude.
Raises
------
ValueError
If no intersections are found at the specified longitude, a ValueError is raised.
If no intersections are found at the specified longitude.
Examples
--------
>>> uxda.constant_longitude_cross_section(lon=-15.5)
>>> # Extract data at 0° longitude
>>> cross_section = uxda.constant_latitude(lon=0.0)
Notes
-----
The accuracy and performance of the function can be controlled using the `method` parameter.
For higher precision requreiments, consider using method='acurate'.
The initial execution time may be significantly longer than subsequent runs
due to Numba's just-in-time compilation. Subsequent calls will be faster due to caching.
"""
faces = self.uxda.uxgrid.get_faces_at_constant_longitude(
lon, use_spherical_bounding_box
Expand Down
80 changes: 39 additions & 41 deletions uxarray/cross_sections/grid_accessor.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,51 +17,50 @@ def __repr__(self):
prefix = "<uxarray.Grid.cross_section>\n"
methods_heading = "Supported Methods:\n"

methods_heading += " * constant_latitude(lat, )\n"
methods_heading += " * constant_latitude(lat, use_spherical_bounding_box, return_face_indices)\n"
methods_heading += " * constant_longitude(lon, use_spherical_bounding_box, return_face_indices)\n"
return prefix + methods_heading

def constant_latitude(
self, lat: float, return_face_indices=False, use_spherical_bounding_box=False
self,
lat: float,
use_spherical_bounding_box: bool = True,
return_face_indices: bool = False,
):
"""Extracts a cross-section of the grid at a specified constant
latitude.
"""Extracts a cross-section of the grid by selecting all faces that
intersect with a specified line of constant latitude.
Parameters
----------
lat : float
The latitude at which to extract the cross-section, in degrees.
return_face_indices : bool, optional
If True, returns both the grid at the specified latitude and the indices
of the intersecting faces. If False, only the grid is returned.
Default is False.
Must be between -90.0 and 90.0
use_spherical_bounding_box : bool, optional
If True, uses a spherical bounding box for intersection calculations.
If True, uses a spherical bounding box for obtaining candidate faces, which considers the extreme cases
along great circle arcs.
return_face_indices : bool, optional
If True, also returns the indices of the faces that intersect with the line of constant latitude.
Returns
-------
grid_at_constant_lat : Grid
The grid with faces that interesected at a given lattitude
faces : array, optional
The indices of the faces that intersect with the specified latitude. This is only
returned if `return_face_indices` is set to True.
uxarray.Grid
A subset of the original grid containing only the faces that intersect
with the specified latitude.
Raises
------
ValueError
If no intersections are found at the specified latitude, a ValueError is raised.
If no intersections are found at the specified latitude.
Examples
--------
>>> grid, indices = grid.cross_section.constant_latitude(
... lat=30.0, return_face_indices=True
... )
>>> grid = grid.cross_section.constant_latitude(lat=-15.5)
>>> # Extract data at 15.5°S latitude
>>> cross_section = grid.constant_latitude(lat=-15.5)
Notes
-----
The accuracy and performance of the function can be controlled using the `method` parameter.
For higher precision requreiments, consider using method='acurate'.
The initial execution time may be significantly longer than subsequent runs
due to Numba's just-in-time compilation. Subsequent calls will be faster due to caching.
"""
faces = self.uxgrid.get_faces_at_constant_latitude(
lat, use_spherical_bounding_box
Expand All @@ -78,46 +77,45 @@ def constant_latitude(
return grid_at_constant_lat

def constant_longitude(
self, lon: float, use_spherical_bounding_box=False, return_face_indices=False
self,
lon: float,
use_spherical_bounding_box: bool = True,
return_face_indices: bool = False,
):
"""Extracts a cross-section of the grid at a specified constant
longitude.
"""Extracts a cross-section of the grid by selecting all faces that
intersect with a specified line of constant longitude.
Parameters
----------
lon : float
The longitude at which to extract the cross-section, in degrees.
Must be between -90.0 and 90.0
use_spherical_bounding_box : bool, optional
If True, uses a spherical bounding box for intersection calculations.
If True, uses a spherical bounding box for obtaining candidate faces, which considers the extreme cases
along great circle arcs.
return_face_indices : bool, optional
If True, returns both the grid at the specified longitude and the indices
of the intersecting faces. If False, only the grid is returned.
Default is False.
If True, also returns the indices of the faces that intersect with the line of constant longitude.
Returns
-------
grid_at_constant_lon : Grid
The grid with faces that interesected at a given longitudes
faces : array, optional
The indices of the faces that intersect with the specified longitude. This is only
returned if `return_face_indices` is set to True.
uxarray.Grid
A subset of the original grid containing only the faces that intersect
with the specified longitude.
Raises
------
ValueError
If no intersections are found at the specified longitude, a ValueError is raised.
If no intersections are found at the specified longitude.
Examples
--------
>>> grid, indices = grid.cross_section.constant_longitude(
... lat=0.0, return_face_indices=True
... )
>>> grid = grid.cross_section.constant_longitude(lat=20.0)
>>> # Extract data at 0° longitude
>>> cross_section = grid.constant_latitude(lon=0.0)
Notes
-----
The accuracy and performance of the function can be controlled using the `method` parameter.
For higher precision requreiments, consider using method='acurate'.
The initial execution time may be significantly longer than subsequent runs
due to Numba's just-in-time compilation. Subsequent calls will be faster due to caching.
"""
faces = self.uxgrid.get_faces_at_constant_longitude(
lon, use_spherical_bounding_box
Expand Down
4 changes: 2 additions & 2 deletions uxarray/grid/grid.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2248,7 +2248,7 @@ def get_edges_at_constant_latitude(self, lat, use_spherical_bounding_box=False):

return edges.squeeze()

def get_faces_at_constant_latitude(self, lat, use_spherical_bounding_box=False):
def get_faces_at_constant_latitude(self, lat, use_spherical_bounding_box=True):
"""
Identifies the indices of faces that intersect with a line of constant latitude.
Expand Down Expand Up @@ -2325,7 +2325,7 @@ def get_edges_at_constant_longitude(self, lon, use_spherical_bounding_box=False)
)
return edges.squeeze()

def get_faces_at_constant_longitude(self, lon, use_spherical_bounding_box=False):
def get_faces_at_constant_longitude(self, lon, use_spherical_bounding_box=True):
"""
Identifies the indices of faces that intersect with a line of constant longitude.
Expand Down

0 comments on commit 7d5860e

Please sign in to comment.