From 7d5860e8ad4d87af293a763e34e4b190a93fc9db Mon Sep 17 00:00:00 2001 From: Philip Chmielowiec Date: Fri, 15 Nov 2024 14:50:53 -0600 Subject: [PATCH] update docstrings (1) --- uxarray/cross_sections/dataarray_accessor.py | 56 ++++++++++---- uxarray/cross_sections/grid_accessor.py | 80 ++++++++++---------- uxarray/grid/grid.py | 4 +- 3 files changed, 81 insertions(+), 59 deletions(-) diff --git a/uxarray/cross_sections/dataarray_accessor.py b/uxarray/cross_sections/dataarray_accessor.py index de35739ab..1330ca22e 100644 --- a/uxarray/cross_sections/dataarray_accessor.py +++ b/uxarray/cross_sections/dataarray_accessor.py @@ -17,29 +17,44 @@ def __repr__(self): prefix = "\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 @@ -47,30 +62,39 @@ def constant_latitude(self, lat: float, use_spherical_bounding_box=False): 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 diff --git a/uxarray/cross_sections/grid_accessor.py b/uxarray/cross_sections/grid_accessor.py index 5b9055166..4266fa6de 100644 --- a/uxarray/cross_sections/grid_accessor.py +++ b/uxarray/cross_sections/grid_accessor.py @@ -17,51 +17,50 @@ def __repr__(self): prefix = "\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 @@ -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 diff --git a/uxarray/grid/grid.py b/uxarray/grid/grid.py index 8f88571fa..ade4c6d27 100644 --- a/uxarray/grid/grid.py +++ b/uxarray/grid/grid.py @@ -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. @@ -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.