Add docstrings

src/toolbox_scs/base/knife_edge.py

@@ -4,6 +4,34 @@ from scipy.optimize import curve_fit
 
 
 def knife_edge(positions, intensities, axisRange=None, p0=None):
+    """
+    The base implementation of the knife-edge scan analysis.
+
+    Calculates the beam radius at 1/e^2 from a knife-edge scan by
+    fitting with erfc function: f(a,b,u) = a*erfc(u) + b or
+    where u = sqrt(2)*(x-x0)/w0 with w0 the beam radius at 1/e^2
+    and x0 the beam center.
+
+    Parameters
+    ----------
+    positions : np.ndarray
+        Motor position values, typically 1D
+    intensities : np.ndarray
+        Intensity values, could be either 1D or 2D, with the number or rows
+        equivalent with the position size
+    axisRange : sequence of two floats or None
+        Edges of the scanning axis between which to apply the fit.
+    p0 : list of floats, numpy 1D array
+        Initial parameters used for the fit: x0, w0, a, b. If None, a beam
+        radius of 100 um is assumed.
+
+    Returns
+    -------
+    width : float
+        The beam radius at 1/e^2
+    std : float
+        The standard deviation of the width
+    """
     popt, pcov = knife_edge_base(positions, intensities,
                                  axisRange=axisRange, p0=p0)
     width, std = 0, 0
@@ -14,7 +42,32 @@ def knife_edge(positions, intensities, axisRange=None, p0=None):
 
 def knife_edge_base(positions, intensities, axisRange=None, p0=None):
     """
-
+    The base implementation of the knife-edge scan analysis.
+
+    Calculates the beam radius at 1/e^2 from a knife-edge scan by
+    fitting with erfc function: f(a,b,u) = a*erfc(u) + b or
+    where u = sqrt(2)*(x-x0)/w0 with w0 the beam radius at 1/e^2
+    and x0 the beam center.
+
+    Parameters
+    ----------
+    positions : np.ndarray
+        Motor position values, typically 1D
+    intensities : np.ndarray
+        Intensity values, could be either 1D or 2D, with the number or rows
+        equivalent with the position size
+    axisRange : sequence of two floats or None
+        Edges of the scanning axis between which to apply the fit.
+    p0 : list of floats, numpy 1D array
+        Initial parameters used for the fit: x0, w0, a, b. If None, a beam
+        radius of 100 um is assumed.
+
+    Returns
+    -------
+    popt : sequence of floats or None
+        The parameters of the resulting fit.
+    pcov : sequence of floats
+        The covariance matrix of the resulting fit.
     """
     # Prepare arrays
     positions, intensities = prepare_arrays(positions, intensities,
@@ -44,6 +97,14 @@ def function_fit(func, x, y, **kwargs):
 
 def prepare_arrays(arrX: np.ndarray, arrY: np.ndarray,
                    xRange=None, yRange=None):
+    """
+    Preprocessing of the input x and y arrays.
+
+    This involves the following steps.
+    1. Converting the arrays to 1D of the same size
+    2. Select the ranges from the input x- and y-ranges
+    3. Retrieve finite values.
+    """
     # Convert both arrays to 1D of the same size
     assert arrX.shape[0] == arrY.shape[0]
     arrX = arrX.flatten()
@@ -72,6 +133,8 @@ def prepare_arrays(arrX: np.ndarray, arrY: np.ndarray,
 
 
 def range_mask(array, minimum=None, maximum=None):
+    """Retrieve the resulting array from the given minimum and maximum
+    """
     default = np.ones(array.shape, dtype=np.bool)
     min_slice, max_slice = default, default
     if minimum is not None: