update jacobian funcs docs

TomDonoghue · TomDonoghue · commit 8fe511b8f004 · 2023-08-20T21:26:04.000-04:00
diff --git a/fooof/core/jacobians.py b/fooof/core/jacobians.py
@@ -1,4 +1,11 @@
-""""Functions for computing Jacobian matrices to be used during fitting."""
+""""Functions for computing Jacobian matrices to be used during fitting.
+
+Notes
+-----
+These functions line up with those in `funcs`.
+The parameters in these functions are labelled {a, b, c, ...}, but follow the order in `funcs`.
+These functions are designed to be passed into `curve_fit` to provide a computed Jacobian.
+"""
 
 import numpy as np
 
@@ -8,7 +15,20 @@
 ## Periodic fit functions
 
 def jacobian_gauss(xs, *params):
-    """Create the Jacobian matrix for the Guassian function."""
+    """Create the Jacobian matrix for the Guassian function.
+
+    Parameters
+    ----------
+    xs : 1d array
+        Input x-axis values.
+    *params : float
+        Parameters for the function.
+
+    Returns
+    -------
+    jacobian : 2d array
+        Jacobian matrix, with shape [len(xs), n_params].
+    """
 
     jacobians = []
     for a, b, c in zip(*[iter(params)] * 3):
@@ -28,7 +48,20 @@ def jacobian_gauss(xs, *params):
 ## Aperiodic fit functions
 
 def jacobian_expo(xs, *params):
-    """Create the Jacobian matrix for the exponential function."""
+    """Create the Jacobian matrix for the exponential function.
+
+    Parameters
+    ----------
+    xs : 1d array
+        Input x-axis values.
+    *params : float
+        Parameters for the function.
+
+    Returns
+    -------
+    jacobian : 2d array
+        Jacobian matrix, with shape [len(xs), n_params].
+    """
 
     a, b, c = params
     jacobian = np.hstack([
@@ -41,7 +74,20 @@ def jacobian_expo(xs, *params):
 
 
 def jacobian_expo_nk(xs, *params):
-    """Create the Jacobian matrix for the exponential no-knee function."""
+    """Create the Jacobian matrix for the exponential no-knee function.
+
+    Parameters
+    ----------
+    xs : 1d array
+        Input x-axis values.
+    *params : float
+        Parameters for the function.
+
+    Returns
+    -------
+    jacobian : 2d array
+        Jacobian matrix, with shape [len(xs), n_params].
+    """
 
     jacobian = np.hstack([
         np.ones([len(xs), 1]),
diff --git a/fooof/tests/core/test_jacobians.py b/fooof/tests/core/test_jacobians.py
@@ -1,6 +1,5 @@
 """Tests for fooof.core.jacobians."""
 
-
 from fooof.core.jacobians import *
 
 ###################################################################################################
