Improve documentation

src/hipscat/catalog/catalog.py

@@ -85,11 +85,11 @@ def filter_by_box(
         self, ra: Tuple[float, float] | None = None, dec: Tuple[float, float] | None = None
     ) -> Catalog:
         """Filter the pixels in the catalog to only include the pixels that overlap with a
-        right ascension or declination range. In case both ranges are provided, filtering the
-        pixels consists of filtering using a polygon.
+        right ascension or declination range. In case both ranges are provided, filtering
+        is performed using a polygon.
 
         Args:
-            ra (Tuple[float, float]): Right Ascension range, in degrees
+            ra (Tuple[float, float]): Right ascension range, in degrees
             dec (Tuple[float, float]): Declination range, in degrees
 
         Returns:

src/hipscat/pixel_math/box_filter.py

@@ -20,11 +20,11 @@ def filter_pixels_by_box(
 ) -> List[HealpixPixel]:
     """Filter the leaf pixels in a pixel tree to return a partition_info dataframe
     with the pixels that overlap with a right ascension or the declination region.
-    Only one of ra and dec must be set, otherwise use polygonal_search.
+    Only one of ra and dec should be set, otherwise one should use polygonal search.
 
     Args:
         pixel_tree (PixelTree): The catalog tree to filter pixels from
-        ra (Tuple[float, float]): Right Ascension range, in degrees
+        ra (Tuple[float, float]): Right ascension range, in degrees
         dec (Tuple[float, float]): Declination range, in degrees
 
     Returns:
@@ -41,42 +41,50 @@ def filter_pixels_by_box(
     return get_filtered_pixel_list(pixel_tree, search_tree)
 
 
-def transform_radec(ra, dec) -> Tuple[Tuple[float, float] | None, Tuple[float, float] | None]:
-    """Transforms ra and dec values before performing the search.
-    Wraps right ascension values to the [0,360] degree range and
-    sorts declination values by ascending order."""
+def transform_radec(
+    ra: Tuple[float, float] | None, dec: Tuple[float, float] | None
+) -> Tuple[Tuple[float, float] | None, Tuple[float, float] | None]:
+    """Transforms ra and dec values so that they are valid when performing the
+    search. Wraps right ascension values to the [0,360] degree range and sorts
+    declination values by ascending order."""
     if ra is not None:
-        ra = tuple(wrap_angles(ra))
+        ra = tuple(wrap_angles(list(ra)))
     if dec is not None:
-        dec = list(np.sort(dec))
+        dec = tuple(np.sort(dec))
     return ra, dec
 
 
-def wrap_angles(ra) -> List[float]:
-    """Wrap angles to the [0,360] degree range."""
-    return Angle(list(ra), u.deg).wrap_at(360 * u.deg).degree
+def wrap_angles(ra: List[float]) -> List[float]:
+    """Wraps angles to the [0,360] degree range.
 
+    Arguments:
+        ra (List[float]): List of right ascension values
 
-def form_polygon(ra, dec) -> List[SphericalCoordinates]:
-    """Checks if both ra and dec were provided and calculates the
-    polygon vertices based on the fact that declination values have
-    been previously sorted.
+    Returns:
+        A list of right ascension values, wrapped to the [0,360] degree range.
+    """
+    return Angle(ra, u.deg).wrap_at(360 * u.deg).degree
+
+
+def form_polygon(ra: Tuple[float, float], dec: Tuple[float, float]) -> List[SphericalCoordinates]:
+    """Checks if both ra and dec were provided and calculates the polygon vertices.
+    Right ascension values should have been wrapped to the [0,360] degree range and
+    declination values sorted in ascending order.
 
     Returns:
-        A list of polygon vertices, if we were provided pairs of
-        ra and dec coordinates, None otherwise.
+        A list of polygon vertices, in spherical coordinates.
     """
     return [(ra[0], dec[0]), (ra[0], dec[1]), (ra[1], dec[1]), (ra[1], dec[0])]
 
 
-def _generate_ra_strip_pixel_tree(ra_range: Tuple[float, float], order: int):
-    """Generates a pixel_tree filled with leaf nodes at a given order that overlap with the ra region"""
+def _generate_ra_strip_pixel_tree(ra_range: Tuple[float, float], order: int) -> PixelTree:
+    """Generates a pixel_tree filled with leaf nodes at a given order that overlap with the ra region."""
     nside = hp.order2nside(order)
-    # The first region contains the north pole
+    # The first region contains the North Pole
     vertices_1 = [(0, 90), (ra_range[0], 0), (ra_range[1], 0)]
     vertices_1 = hp.ang2vec(*np.array(vertices_1).T, lonlat=True)
     pixels_in_range_1 = hp.query_polygon(nside, vertices_1, inclusive=True, nest=True)
-    # The second contains the south pole
+    # The second region contains the South Pole
     vertices_2 = [(ra_range[0], 0), (0, -90), (ra_range[1], 0)]
     vertices_2 = hp.ang2vec(*np.array(vertices_2).T, lonlat=True)
     pixels_in_range_2 = hp.query_polygon(nside, vertices_2, inclusive=True, nest=True)
@@ -86,8 +94,8 @@ def _generate_ra_strip_pixel_tree(ra_range: Tuple[float, float], order: int):
     return PixelTreeBuilder.from_healpix(pixel_list)
 
 
-def _generate_dec_strip_pixel_tree(dec_range: Tuple[float, float], order: int):
-    """Generates a pixel_tree filled with leaf nodes at a given order that overlap with the dec region"""
+def _generate_dec_strip_pixel_tree(dec_range: Tuple[float, float], order: int) -> PixelTree:
+    """Generates a pixel_tree filled with leaf nodes at a given order that overlap with the dec region."""
     nside = hp.order2nside(order)
     sorted_dec = np.sort([90 - dec if dec > 0 else 90 + abs(dec) for dec in dec_range])
     min_colatitude = np.radians(sorted_dec[0])

src/hipscat/pixel_math/validators.py

@@ -1,13 +1,14 @@
 from __future__ import annotations
 
 from enum import Enum
-from typing import List
+from typing import List, Tuple
 
 import numpy as np
 
 
 class ValidatorsErrors(str, Enum):
     """Error messages for the coordinate validators"""
+
     INVALID_DEC = "declination must be in the -90.0 to 90.0 degree range"
     INVALID_RADIUS = "cone radius must be positive"
     INVALID_NUM_VERTICES = "polygon must contain a minimum of 3 vertices"
@@ -38,7 +39,7 @@ def validate_declination_values(dec: float | List[float]):
         ValueError if declination values are not in the [-90,90] degree range
     """
     dec_values = np.array(dec)
-    lower_bound, upper_bound = -90., 90.
+    lower_bound, upper_bound = -90.0, 90.0
     if not np.all((dec_values >= lower_bound) & (dec_values <= upper_bound)):
         raise ValueError(ValidatorsErrors.INVALID_DEC.value)
 
@@ -87,9 +88,18 @@ def is_polygon_degenerate(vertices: np.ndarray) -> bool:
     return bool(np.isclose(center_distance, 0))
 
 
-def validate_box_search(ra, dec):
+def validate_box_search(ra: Tuple[float, float] | None, dec: Tuple[float, float] | None):
     """Checks if ra and dec values are valid for the box search.
-    They must be pairs (of minimum and maximum value)."""
+    They must be pairs (of minimum and maximum value, in degrees).
+
+    Arguments:
+        ra (Tuple[float, float]): Right ascension range, in degrees
+        dec (Tuple[float, float]): Declination range, in degrees
+
+    Raises:
+        ValueError, if declination values are out of range [-90,90]
+        or if no range was provided.
+    """
     values_provided = False
     if ra is not None and len(ra) == 2:
         values_provided = True