docs: refactor docstrings for autoarray/structures package

- abstract_structure: add docstrings to all undocumented properties
  (geometry, derive_grid, derive_indexes, derive_mask, shape_slim,
  shape_native, pixel_scales, pixel_scale, header_dict, pixel_area,
  total_area, origin, unmasked_grid, total_pixels); expand
  trimmed_after_convolution_from (was bare NotImplementedError)

- arrays/uniform_2d: add missing params (header, skip_mask, xp) to
  __init__; add docstrings to in_counts, in_counts_per_second,
  original_orientation, readout_offsets; fix "locaiton" typo; fix
  self-referential sentence in brightest_sub_pixel_coordinate; fix
  no_mask example (was aa.Array2D.manual + syntax error with period)

- arrays/array_2d_util: fix "input array input a convert" description;
  add docstring to check_array_2d; fix "oigin"/"reszied" typos;
  fix wrong function name in example (index_flat_for_index_2d_from →
  index_slim_for_index_2d_from); remove duplicate array_2d_native param

- arrays/irregular: add docstrings to values and native properties

- arrays/uniform_1d: add full __init__ docstring; fix "Make Array2D"
  comment → "Make Array1D"

- grids/grid_2d_util: fix "he " → "The" (×2); fix "silm" → "slim";
  fix "flloat" → "float" (×2); fix mask_2d param name in grid_2d_slim_from;
  add docstrings to convert_grid, check_grid_slim, check_grid_2d,
  check_grid_2d_and_mask_2d

- grids/grid_1d_util: rewrite convert_grid_1d docstring (was
  copy-pasted from Grid2D with wrong class/param names grid_2d/mask_2d);
  fix grid_1d_slim_via_mask_from ("2D mask" → "1D mask", wrong example)

- grids/uniform_1d: fix __init__ params (was "(y,x)" for a 1D grid);
  fix no_mask params and example ("autogrid", "np.ndgrid", "Grid2D");
  fix __native__ section referencing Grid2D instead of Grid1D

- grids/irregular_2d: add docstrings to values, slim, native properties;
  fix "*Coordinate* instance" → "Grid2DIrregular instance" (×2)

- visibilities: fix "visibilitiy" typo

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: 2 people

autoarray/structures/abstract_structure.py

@@ -29,62 +29,125 @@ def slim(self) -> "Structure":
 
     @property
     def geometry(self):
+        """
+        The geometry object of the mask associated with this structure, which defines coordinate conversions
+        between pixel units and scaled units.
+        """
         return self.mask.geometry
 
     @property
     def derive_grid(self) -> DeriveGrid2D:
+        """
+        The ``DeriveGrid2D`` object of the mask, used to compute derived grids of (y,x) coordinates such as
+        the edge grid, border grid, and full unmasked grid.
+        """
         return self.mask.derive_grid
 
     @property
     def derive_indexes(self) -> DeriveIndexes2D:
+        """
+        The ``DeriveIndexes2D`` object of the mask, used to compute index arrays that map data between the
+        ``slim`` (1D unmasked) and ``native`` (2D full-shape) representations.
+        """
         return self.mask.derive_indexes
 
     @property
     def derive_mask(self) -> DeriveMask2D:
+        """
+        The ``DeriveMask2D`` object of the mask, used to compute derived masks such as the edge mask,
+        border mask, and blurring mask.
+        """
         return self.mask.derive_mask
 
     @property
     def shape_slim(self) -> int:
+        """
+        The 1D shape of the data structure in its ``slim`` representation, equal to the number of unmasked pixels.
+        """
         return self.mask.shape_slim
 
     @property
     def shape_native(self) -> Tuple[int, ...]:
+        """
+        The shape of the data structure in its ``native`` representation (e.g. ``(total_y_pixels, total_x_pixels)``
+        for a 2D structure).
+        """
         return self.mask.shape
 
     @property
     def pixel_scales(self) -> Tuple[float, ...]:
+        """
+        The (y,x) scaled units to pixel units conversion factors of every pixel, as a tuple of floats.
+        """
         return self.mask.pixel_scales
 
     @property
     def pixel_scale(self) -> float:
+        """
+        The pixel scale as a single float value. Assumes all pixel scales are equal (e.g. square pixels).
+        """
         return self.mask.pixel_scale
 
     @property
     def header_dict(self) -> Dict:
+        """
+        The FITS header dictionary of the mask associated with this structure, containing pixel scale and origin entries.
+        """
         return self.mask.header_dict
 
     @property
     def pixel_area(self):
+        """
+        The area of a single pixel in scaled units squared (``pixel_scales[0] * pixel_scales[1]``).
+
+        Only valid for 2D structures; raises ``GridException`` for 1D structures.
+        """
         if len(self.pixel_scales) != 2:
             raise exc.GridException("Cannot compute area of structure which is not 2D.")
 
         return self.pixel_scales[0] * self.pixel_scales[1]
 
     @property
     def total_area(self):
+        """
+        The total area of all unmasked pixels in scaled units squared (``total_pixels * pixel_area``).
+        """
         return self.total_pixels * self.pixel_area
 
     @property
     def origin(self) -> Tuple[int, ...]:
+        """
+        The (y,x) scaled units origin of the mask's coordinate system.
+        """
         return self.mask.origin
 
     @property
     def unmasked_grid(self) -> Union[Grid1D, Grid2D]:
+        """
+        A grid of (y,x) coordinates of every pixel in the full mask shape (including masked pixels), using
+        the mask's geometry to compute each pixel's scaled coordinate.
+        """
         return self.mask.derive_grid.all_false
 
     @property
     def total_pixels(self) -> int:
+        """
+        The total number of unmasked pixels in the data structure (its ``slim`` length).
+        """
         return self.shape[0]
 
     def trimmed_after_convolution_from(self, kernel_shape) -> "Structure":
+        """
+        Trim the data structure back to its original shape after PSF convolution has been performed on a
+        padded version of it.
+
+        This is the inverse of ``padded_before_convolution_from``: first the data structure is padded so
+        that edge-pixel signal is not lost during convolution, and then this method trims the result back
+        to the original shape.
+
+        Parameters
+        ----------
+        kernel_shape
+            The 2D shape of the convolution kernel used to pad and trim the data structure.
+        """
         raise NotImplementedError

autoarray/structures/arrays/array_2d_util.py

@@ -12,7 +12,7 @@
 
 def convert_array(array: Union[np.ndarray, List]) -> np.ndarray:
     """
-    If the input array input a convert is of type list, convert it to type NumPy array.
+    Convert the input array to a NumPy ``ndarray`` if it is a list, or unwrap it if it is an autoarray object.
 
     Parameters
     ----------
@@ -32,6 +32,16 @@ def convert_array(array: Union[np.ndarray, List]) -> np.ndarray:
 
 
 def check_array_2d(array_2d: np.ndarray):
+    """
+    Check that an array intended for use as an ``Array2D`` slim representation has exactly 1 dimension.
+
+    Raises ``ArrayException`` if the array is not 1D.
+
+    Parameters
+    ----------
+    array_2d
+        The array to check, which must have shape [total_unmasked_pixels].
+    """
     if len(array_2d.shape) != 1:
         raise exc.ArrayException(
             "An array input into the Array2D.__new__ method is not of shape 1."
@@ -281,9 +291,9 @@ def resized_array_2d_from(
     resized_shape
         The (y,x) new pixel dimension of the trimmed array.
     origin
-        The oigin of the resized array, e.g. the central pixel around which the array is extracted.
+        The origin of the resized array, e.g. the central pixel around which the array is extracted.
     pad_value
-        If the reszied array is bigger in size than the input array, the value the padded edge values are filled in
+        If the resized array is bigger in size than the input array, the value the padded edge values are filled in
         using.
 
     Returns
@@ -405,7 +415,7 @@ def index_slim_for_index_2d_from(indexes_2d: np.ndarray, shape_native) -> np.nda
     Examples
     --------
     indexes_2d = np.array([[0,0], [1,0], [2,0], [2,2]])
-    indexes_flat = index_flat_for_index_2d_from(indexes_2d=indexes_2d, shape=(3,3))
+    indexes_slim = index_slim_for_index_2d_from(indexes_2d=indexes_2d, shape_native=(3,3))
     """
     # Calculate 1D indexes as row_index * number_of_columns + col_index
     index_slim_for_index_native_2d = (
@@ -434,11 +444,9 @@ def array_2d_slim_from(
     Parameters
     ----------
     array_2d_native
-        A 2D array of values on the dimensions of the grid.
+        A 2D array of values on the dimensions of the grid, with shape [total_y_pixels, total_x_pixels].
     mask_2d
         A 2D array of bools, where `False` values mean unmasked and are included in the mapping.
-    array_2d_native
-        The 2D array of values which are mapped to a 1D array.
 
     Returns
     -------

autoarray/structures/arrays/irregular.py

@@ -45,6 +45,9 @@ def __init__(self, values: Union[List, np.ndarray]):
 
     @property
     def values(self):
+        """
+        The raw underlying 1D ndarray of values, with shape [total_values].
+        """
         return self.array
 
     @property
@@ -56,6 +59,10 @@ def slim(self) -> "ArrayIrregular":
 
     @property
     def native(self) -> Structure:
+        """
+        The ``ArrayIrregular`` in its ``native`` representation. For an irregular array there is no 2D native
+        format, so this returns the array as-is.
+        """
         return self
 
     @property

autoarray/structures/arrays/uniform_1d.py

@@ -25,6 +25,29 @@ def __init__(
         store_native: bool = False,
         xp=np,
     ):
+        """
+        A uniform 1D array of values, paired with a 1D mask of pixels.
+
+        Each entry of an ``Array1D`` corresponds to a value at the centre of a pixel in its corresponding ``Mask1D``.
+        It is ordered such that pixels begin from the left of the corresponding mask and go right.
+
+        Like ``Array2D``, the ``Array1D`` supports ``slim`` (1D, unmasked only) and ``native`` (1D, full length)
+        data representations.
+
+        Parameters
+        ----------
+        values
+            The values of the array, input in the ``slim`` or ``native`` format.
+        mask
+            The 1D mask associated with the array, defining which pixels each array value is paired with.
+        header
+            Optional metadata header associated with the array (e.g. from a FITS file).
+        store_native
+            If True, the ndarray is stored in its native format [total_pixels]. This avoids mapping large data
+            arrays to and from the slim / native formats, which can be a computational bottleneck.
+        xp
+            The array module to use (default ``numpy``; pass ``jax.numpy`` for JAX support).
+        """
 
         values = array_1d_util.convert_array_1d(
             array_1d=values, mask_1d=mask, store_native=store_native, xp=xp
@@ -66,7 +89,7 @@ def no_mask(
 
             array_1d = aa.Array1D.no_mask(values=np.array([1.0, 2.0, 3.0, 4.0]), pixel_scales=1.0)
 
-            # Make Array2D from input list.
+            # Make Array1D from input list.
 
             array_1d = aa.Array1D.no_mask(values=[1.0, 2.0, 3.0, 4.0], pixel_scales=1.0)
 

autoarray/structures/arrays/uniform_2d.py

@@ -187,9 +187,15 @@ def __init__(
         mask
             The 2D mask associated with the array, defining the pixels each array value in its ``slim`` representation
             is paired with.
+        header
+            Optional metadata header (e.g. from a FITS file) associated with the array.
         store_native
             If True, the ndarray is stored in its native format [total_y_pixels, total_x_pixels]. This avoids
             mapping large data arrays to and from the slim / native formats, which can be a computational bottleneck.
+        skip_mask
+            If True, masking is skipped and values are stored as-is without zeroing masked entries.
+        xp
+            The array module to use (default ``numpy``; pass ``jax.numpy`` for JAX support).
 
         Examples
         --------
@@ -334,22 +340,39 @@ def native_skip_mask(self) -> "Array2D":
 
     @property
     def in_counts(self) -> "Array2D":
+        """
+        The array converted from electrons-per-second (eps) to total counts, using the exposure time stored
+        in the associated ``Header``.
+        """
         return self.header.array_eps_to_counts(array_eps=self)
 
     @property
     def in_counts_per_second(self) -> "Array2D":
+        """
+        The array converted from electrons-per-second (eps) to counts-per-second, via an intermediate
+        conversion to total counts using the ``Header`` exposure time.
+        """
         return self.header.array_counts_to_counts_per_second(
             array_counts=self.in_counts
         )
 
     @property
     def original_orientation(self) -> Union[np.ndarray, "Array2D"]:
+        """
+        The array rotated back to its original CCD read-out orientation, using the read-out-electronics (ROE)
+        corner stored in the associated ``Header``.
+        """
         return layout_util.rotate_array_via_roe_corner_from(
             array=self, roe_corner=self.header.original_roe_corner
         )
 
     @property
     def readout_offsets(self) -> Tuple[int, int]:
+        """
+        The (y,x) pixel offsets of the read-out electronics corner, taken from the associated ``Header``.
+
+        Returns ``(0, 0)`` if no header is present or no readout offsets are stored in the header.
+        """
         if self.header is not None:
             if self.header.readout_offsets is not None:
                 return self.header.readout_offsets
@@ -438,10 +461,10 @@ def brightest_sub_pixel_coordinate_in_region_from(
 
         For example, if the input region is `region=(-0.15, 0.25, 0.35, 0.55)` the code finds all pixels inside of
         this region in scaled units, finds the brightest pixel of those pixels, and then on a 3x3 grid surrounding
-        this pixel determines the locaiton of the brightest sub pixel using a weighted centre calculation.
+        this pixel determines the location of the brightest sub pixel using a weighted centre calculation.
 
-        The centre of the brightest pixel is returned, the function `brightest_sub_pixel_coordinate_in_region_from`
-        performs a sub pixel calculation to return the brightest sub pixel coordinate.
+        Unlike ``brightest_coordinate_in_region_from``, which returns the centre of the brightest pixel, this
+        function performs a weighted-centroid sub-pixel calculation to return a more precise coordinate.
 
         Parameters
         ----------
@@ -621,9 +644,9 @@ def no_mask(
             # Make Array2D from input list, native format
             # (This array has shape_native=(2,2)).
 
-            array_2d = aa.Array2D.manual(
-                array=np.array([[1.0, 2.0], [3.0, 4.0]]),
-                pixel_scales=1.0.
+            array_2d = aa.Array2D.no_mask(
+                values=np.array([[1.0, 2.0], [3.0, 4.0]]),
+                pixel_scales=1.0,
             )
         """
 

autoarray/structures/grids/grid_1d_util.py

@@ -16,26 +16,28 @@ def convert_grid_1d(
     grid_1d: Union[np.ndarray, List], mask_1d: Mask1D, store_native: bool = False, xp=np
 ) -> np.ndarray:
     """
-    The `manual` classmethods in the Grid2D object take as input a list or ndarray which is returned as a Grid2D.
+    The ``manual`` classmethods in the ``Grid1D`` object take as input a list or ndarray which is returned as a ``Grid1D``.
 
-    This function performs the following and checks and conversions on the input:
+    This function performs the following checks and conversions on the input:
 
-    1: If the input is a list, convert it to an ndarray.
-    2: Check that the number of pixels in the array is identical to that of the mask.
-    3) Map the input ndarray to its `slim` representation.
+    1. If the input is a list, convert it to an ndarray.
+    2. Check that the number of pixels in the array is identical to that of the mask.
+    3. Map the input ndarray to its ``slim`` representation.
 
-    For a Grid2D, `slim` refers to a 2D NumPy array of shape [total_coordinates, 2] and `native` a 3D NumPy array of
-    shape [total_y_coordinates, total_x_coordinates, 2]
+    For a ``Grid1D``, ``slim`` refers to a 1D NumPy array of shape [total_unmasked_pixels] and ``native`` a 1D
+    NumPy array of shape [total_pixels].
 
     Parameters
     ----------
-    grid_2d
-        The input (y,x) grid of coordinates which is converted to an ndarray if it is a list.
-    mask_2d
-        The mask of the output Array2D.
+    grid_1d
+        The input (x,) grid of coordinates which is converted to an ndarray if it is a list.
+    mask_1d
+        The mask of the output ``Grid1D``.
     store_native
-        If True, the ndarray is stored in its native format [total_y_pixels, total_x_pixels, 2]. This avoids
-        mapping large data arrays to and from the slim / native formats, which can be a computational bottleneck.
+        If True, the ndarray is stored in its native format [total_pixels]. This avoids mapping large data arrays
+        to and from the slim / native formats, which can be a computational bottleneck.
+    xp
+        The array module to use (default ``numpy``; pass ``jax.numpy`` for JAX support).
     """
 
     grid_1d = grid_2d_util.convert_grid(grid=grid_1d)
@@ -114,20 +116,20 @@ def grid_1d_slim_via_mask_from(
         A 1D array of bools, where `False` values are unmasked and therefore included as part of the calculated
         grid.
     pixel_scales
-        The (x) scaled units to pixel units conversion factor of the 2D mask array.
+        The (x,) scaled units to pixel units conversion factor of the 1D mask array.
     origin
-        The (x) origin of the 2D array, which the grid is shifted around.
+        The (x,) origin of the 1D array, which the grid is shifted around.
 
     Returns
     -------
     ndarray
-        A grid of (x) scaled coordinates at the centre of every pixel unmasked pixel on the 2D mask
+        A grid of (x) scaled coordinates at the centre of every unmasked pixel in the 1D mask
         array. The grid array has dimensions (total_unmasked_pixels, ).
 
     Examples
     --------
     mask = np.array([True, False, True, False, False, False])
-    grid_slim = grid_1d_via_mask_from(mask_1d=mask_1d, pixel_scales=(0.5, 0.5), origin=(0.0, 0.0))
+    grid_slim = grid_1d_slim_via_mask_from(mask_1d=mask, pixel_scales=(0.5,), origin=(0.0,))
     """
     centres_scaled = geometry_util.central_scaled_coordinate_1d_from(
         shape_slim=mask_1d.shape, pixel_scales=pixel_scales, origin=origin