Update docstrings

CHANGELOG.md

@@ -1,6 +1,7 @@
 # OpenGHG Inversions Change Log
 
 # Version 0.2.0
+- Update docstrings
 
 - Cleaned up `utils.py`: adding typing, and updated docstrings [#PR 158](https://github.com/openghg/openghg_inversions/pull/158) 
 

openghg_inversions/basis/_wrapper.py

@@ -15,7 +15,7 @@ def basis_functions_wrapper(
     species: str,
     domain: str,
     start_date: str,
-    emissions_name: list[str],
+    emissions_name: list[str] | None,
     nbasis: int,
     use_bc: bool,
     basis_algorithm: Optional[str] = None,

openghg_inversions/basis/algorithms/_quadtree.py

@@ -15,20 +15,20 @@ class quadTreeNode:
     'child1', 'child2', 'child3', 'child4' store its children 
     nodes (e.g. its subdivisions). 
     """
-    def __init__(self, xStart, xEnd, yStart, yEnd):
+    def __init__(self, xStart : int, xEnd : int, yStart : int, yEnd : int):
         """Init quadTreeNode.
 
         Args :
-            xStart (int): 
+            xStart: 
                 index of the grid on the first axis
                 on which the node starts.
-            xEnd (int): 
+            xEnd: 
                 index of the grid on the first axis
                 on which the node ends.
-            yStart (int): 
+            yStart: 
                 index of the grid on the second axis
                 on which the node starts.
-            yEnd (int): 
+            yEnd: 
                 index of the grid on the second axis
                 on which the node ends.
         """
@@ -49,15 +49,15 @@ def isLeaf(self):
         else:
             return True
 
-    def createChildren(self, grid, limit):
+    def createChildren(self, grid : np.ndarray, limit : float):
         """
         Create children nodes. If finest resolution or bucket level reached,
         no children nodes are created and the node is thus a leaf.
 
         Args :
-            grid (array):
+            grid:
                 2d numpy array to wich the quadtree division is applied.
-            limit (float):
+            limit:
                 Bucket level (i.e. targeted resolution which is compared to the 
                 sum of the grid points in the node).
         """
@@ -88,12 +88,12 @@ def createChildren(self, grid, limit):
         self.child3.createChildren(grid, limit)
         self.child4.createChildren(grid, limit)
 
-    def appendLeaves(self, leafList):
+    def appendLeaves(self, leafList : list):
         """
         Recursively look for leaves in the node offsprings and append them to the leafList.
 
         Args :
-          leafList (list): 
+          leafList: 
             list containing all the leaves, i.e. basis regions that will be used
             in the hbmcmc inversion.
         """
@@ -107,7 +107,8 @@ def appendLeaves(self, leafList):
             self.child4.appendLeaves(leafList)
 
 
-def quadTreeGrid(grid, limit):
+def quadTreeGrid(grid : np.ndarray, 
+                 limit : float) -> np.ndarray:
     """
     Apply quadtree division algorithm.
 
@@ -137,7 +138,9 @@ def quadTreeGrid(grid, limit):
     return outputGrid
 
 
-def get_quadtree_basis(fps: np.ndarray, nbasis: int, seed: Optional[int] = None) -> np.ndarray:
+def get_quadtree_basis(fps: np.ndarray, 
+                       nbasis: int, 
+                       seed: Optional[int] = None) -> np.ndarray:
     """Given an array and a specified number of basis functions, return basis regions specified by
     the quadtree algorithm.
 

openghg_inversions/basis/algorithms/_weighted.py

@@ -3,12 +3,13 @@
 by input data.
 """
 from pathlib import Path
+from typing import Optional
 import numpy as np
 import xarray as xr
 
 
 # BUCKET BASIS FUNCTIONS
-def load_landsea_indices():
+def load_landsea_indices() -> np.ndarray:
     """
     Load UKMO array with indices that separate
     land and sea regions in EUROPE domain
@@ -21,7 +22,10 @@ def load_landsea_indices():
     return landsea_indices["country"].values
 
 
-def bucket_value_split(grid, bucket, offset_x=0, offset_y=0):
+def bucket_value_split(grid : np.ndarray, 
+                       bucket : float, 
+                       offset_x : Optional[int]=0, 
+                       offset_y : Optional[int]=0) -> list[tuple]:
     """
     Algorithm that will split the input grid (e.g. fp * flux)
     such that the sum of each basis function region will
@@ -32,24 +36,21 @@ def bucket_value_split(grid, bucket, offset_x=0, offset_y=0):
          larger bucket value ==> fewer regions
 
     Args:
-        grid (np.array):
+        grid:
             2D grid of footprints * flux, or whatever
             grid you want to split. Could be: population
             data, spatial distribution of bakeries, you chose!
-
-        bucket (float):
+        bucket:
             Maximum value for each basis function region
-
-        offset_x (int):
+        offset_x:
             Start index of the region on first axis of the grid
             Default 0
-
-        offset_y (int):
+        offset_y:
             Start index of the region on second axis of the grid
             Default 0
 
     Returns:
-        array of tuples that define the indices for each basis function region
+        list of tuples that define the indices for each basis function region
         [(ymin0, ymax0, xmin0, xmax0), ..., (yminN, ymaxN, xminN, xmaxN)]
     """
 
@@ -70,48 +71,47 @@ def bucket_value_split(grid, bucket, offset_x=0, offset_y=0):
             )
 
 
-# Optimize bucket value to number of desired regions
-def get_nregions(bucket, grid):
+def get_nregions(bucket : float, 
+                 grid : np.ndarray) -> int:
     """Optimize bucket value to number of desired regions.
 
     Args:
-        grid (np.array):
+        bucket:
+            Maximum value for each basis function region
+        grid:
             2D grid of footprints * flux, or whatever
             grid you want to split. Could be: population
-            data, spatial distribution of bakeries, you chose!
-
-        bucket (float):
-            Maximum value for each basis function region
+            data, spatial distribution of bakeries, you choose!
 
     Return :
-        no. (int) of basis functions for bucket value
+        number of basis functions for bucket value
     """
     return np.max(bucket_split_landsea_basis(grid, bucket))
 
 
-def optimize_nregions(bucket, grid, nregion, tol):
+def optimize_nregions(bucket : float, 
+                      grid : np.ndarray, 
+                      nregion : int, 
+                      tol : int) -> float:
     """
     Optimize bucket value to obtain nregion basis functions
     within +/- tol.
 
     Args:
-        grid (np.array):
+        bucket:
+            Maximum value for each basis function region
+        grid:
             2D grid of footprints * flux, or whatever
             grid you want to split. Could be: population
-            data, spatial distribution of bakeries, you chose!
-
-        bucket (float):
-            Maximum value for each basis function region
-
-        nregion (int):
+            data, spatial distribution of bakeries, you choose!
+        nregion:
             Number of desired basis function regions
-
-        tol (int):
+        tol:
             Tolerance to find number of basis function regions.
             i.e. optimizes nregions to +/- tol
 
     Return :
-        Optimized bucket value (float)
+        Optimized bucket value
     """
     # print(bucket, get_nregions(bucket, grid))
     if get_nregions(bucket, grid) <= nregion + tol and get_nregions(bucket, grid) >= nregion - tol:
@@ -126,18 +126,18 @@ def optimize_nregions(bucket, grid, nregion, tol):
         return optimize_nregions(bucket, grid, nregion, tol)
 
 
-def bucket_split_landsea_basis(grid, bucket):
+def bucket_split_landsea_basis(grid : np.ndarray, 
+                               bucket : float) -> np.ndarray:
     """
     Same as bucket_split_basis but includes
     land-sea split. i.e. basis functions cannot overlap sea and land
 
     Args:
-        grid (np.array):
+        grid:
             2D grid of footprints * flux, or whatever
             grid you want to split. Could be: population
-            data, spatial distribution of bakeries, you chose!
-
-        bucket (float):
+            data, spatial distribution of bakeries, you choose!
+        bucket:
             Maximum value for each basis function region
 
     Returns:
@@ -171,32 +171,31 @@ def bucket_split_landsea_basis(grid, bucket):
     return mybasis_function
 
 
-def nregion_landsea_basis(grid, bucket=1, nregion=100, tol=1):
+def nregion_landsea_basis(grid : np.ndarray,
+                          bucket : float = 1,
+                          nregion : int = 100, 
+                          tol : int = 1) -> np.ndarray:
     """
     Obtain basis function with nregions (for land-sea split)
 
     Args:
-        grid (np.array):
+        grid:
             2D grid of footprints * flux, or whatever
             grid you want to split. Could be: population
-            data, spatial distribution of bakeries, you chose!
-
-        bucket (float):
+            data, spatial distribution of bakeries, you choose!
+        bucket:
             Initial bucket value for each basis function region.
             Defaults to 1
-
-        nregion (int):
+        nregion:
             Number of desired basis function regions
             Defaults to 100
-
-        tol (int):
+        tol:
             Tolerance to find number of basis function regions.
             i.e. optimizes nregions to +/- tol
             Defaults to 1
 
     Returns:
-        basis_function (np.array):
-            2D basis function array
+        basis_function: 2D basis function array
     """
     bucket_opt = optimize_nregions(bucket, grid, nregion, tol)
     basis_function = bucket_split_landsea_basis(grid, bucket_opt)