docs clean up

docs/source/conf.py

@@ -196,3 +196,10 @@
 
 def setup(app):
     app.add_css_file('custom.css')
+
+# Looks for objects in external projects
+intersphinx_mapping = {
+    'scipy': ('https://docs.scipy.org/doc/scipy/reference/', None),
+    'uncertainties': ('https://uncertainties-python-package.readthedocs.io/en/latest/', None),
+    'pandas': ('https://pandas.pydata.org/docs/', None)
+}

islatu/background.py

@@ -1,6 +1,5 @@
 """
-Background substraction is a necssary component of reflectometry reduction,
-where the background scattering is removed from the reflected intensity.
+Background substraction is a necssary component of reflectometry reduction, where the background scattering is removed from the reflected intensity.
 
 Herein are some function to enable that for a two-dimensional detector image.
 """
@@ -20,22 +19,19 @@ def bivariate_normal(data, mu_1, mu_2, sigma_1, sigma_2, offset, factor):
     """
     Produce a bivariate normal distribution.
 
-    Note: the covariance of the two dimensions is assumed to be zero to
-    unsure greater stability.
+    *Note*: the covariance of the two dimensions is assumed to be zero to unsure greater stability.
 
     Args:
-        data (array_like): Two-dimensional abscissa data.
-        mu_1 (float): Mean in dimension 0 (horizontal).
-        mu_2 (float): Mean in dimension 1 (vertical).
-        sigma_1 (float): Variance in dimension 0 (horizontal).
-        sigma_2 (float): Variance in dimension 1 (vertical).
-        offset (float): Offset from the 0 for the ordinate, this is the
-            background level.
-        factor (float): Multiplicative factor for area of normal distribution.
+        data (:py:attr:`array_like`): Two-dimensional abscissa data.
+        mu_1 (:py:attr:`float`): Mean in dimension 0 (horizontal).
+        mu_2 (:py:attr:`float`): Mean in dimension 1 (vertical).
+        sigma_1 (:py:attr:`float`): Variance in dimension 0 (horizontal).
+        sigma_2 (:py:attr:`float`): Variance in dimension 1 (vertical).
+        offset (:py:attr:`float`): Offset from the 0 for the ordinate, this is the background level.
+        factor (:py:attr:`float`): Multiplicative factor for area of normal distribution.
 
     Returns:
-        (array_like): Flattened ordinate data for bivariate normal
-            distribution.
+        :py:attr:`array_like`: Flattened ordinate data for bivariate normal distribution.
     """
     # Setting the data up in the correct format
     pos = np.empty(data[0].shape + (2,))
@@ -53,18 +49,16 @@ def fit_gaussian_2d(image, image_e, p0=None, bounds=None):
     vertical distribution width.
 
     Args:
-        image (array_like): The data to fit the Gaussian to.
-        image_e (array_like): The data uncertainty.
-        p0 (list, optional): An initial guess at the parameters. Defaults to
-        values based on the image.
-        bounds (tuple_of_list, optional): Bounds for the fitting. Defaults to
-        values based on the image.
+        image (:py:attr:`array_like`): The data to fit the Gaussian to.
+        image_e (:py:attr:`array_like`): The data uncertainty.
+        p0 (:py:attr:`list`, optional): An initial guess at the parameters. Defaults to values based on the image.
+        bounds (:py:attr:`list` of :py:attr:`tuple`, optional): Bounds for the fitting. Defaults to values based on the image.
 
     Returns:
-        (tuple): tuple containing:
-            - (np.ndarray): The results (with uncertainties) for each of the 6 parameters fit.
-            - (int): The index of the offset.
-            - (int): The index of the vertical distribution width.
+        :py:attr:`tuple`: Containing:
+            - :py:attr:`array_like`: The results (with uncertainties) for each of the 6 parameters fit.
+            - :py:attr:`int`: The index of the offset.
+            - :py:attr:`int`: The index of the vertical distribution width.
     """
     # Setting default values
     if p0 is None:

islatu/corrections.py

@@ -20,13 +20,12 @@ def footprint_correction(beam_width, sample_size, theta):
     scattering geometry, where the beam is Gaussian in shape.
 
     Args:
-        beam_width (float): Width of incident beam, in metres.
-        sample_size (uncertainties.core.Variable): Width of sample in the
-            dimension of the beam, in metres.
-        theta (float): Incident angle, in degrees.
+        beam_width (:py:attr:`float`): Width of incident beam, in metres.
+        sample_size (:py:class:`uncertainties.core.Variable`): Width of sample in the dimension of the beam, in metres.
+        theta (:py:attr:`float`): Incident angle, in degrees.
 
     Returns:
-        (uncertainties.core.Variable): Correction factor.
+        (:py:class:`uncertainties.core.Variable`): Correction factor.
     """
     beam_sd = beam_width / 2 / np.sqrt(2 * np.log(2))
     length = sample_size * unp.sin(unp.radians(theta))
@@ -45,13 +44,16 @@ def get_interpolator(file_path, parser, q_axis_name='qdcd_', intensity_axis_name
     Get an interpolator object from scipy, this is useful for the DCD q-normalisation step.
 
     Args:
-        file_path (str): File path to the normalisation file.
-        parser (callable): Parser function for the normalisation file.
-        q_axis_name (str, optional): Label for the q-value in the normalisation file. Defaults to ``'qdcd_'``.
-        intensity_axis_name (str, optional): Label for the intensity in the normalisation file. Defaults to ``'adc2'``.
+        file_path (:py:attr:`str`): File path to the normalisation file.
+        parser (:py:attr:`callable`): Parser function for the normalisation file.
+        q_axis_name (:py:attr:`str`, optional): Label for the q-value in the normalisation file. Defaults to ``'qdcd_'``.
+        intensity_axis_name (:py:attr:`str`, optional): Label for the intensity in the normalisation file. Defaults to ``'adc2'``.
 
     Returns:
-        (scipy.interpolator): Interpolation object. 
+        :py:attr:`tuple`: Containing:
+            - :py:attr:`array_like`: Interpolation knots.
+            - :py:attr:`array_like`: B-spline coefficients.
+            - :py:attr:`int`: Degree of spline.
     """
     normalisation_data = parser(file_path)[1]
     return splrep(normalisation_data[q_axis_name], normalisation_data[intensity_axis_name])

islatu/cropping.py

@@ -12,18 +12,17 @@
 
 def crop_2d(array, x_start, x_end, y_start, y_end):
     """
-    Crop the data (`array`) with some given start and stop point.
+    Crop the data (:py:attr:`array`) with some given start and stop point.
 
     Args:
-        array (np.ndarray): The intensity map collected by the 2
-            dimensional detector.
-        x_start (int): Start point in x-axis.
-        x_end (int): End point in x-axis.
-        y_start (int): Start point in y-axis.
-        y_end (int): End point in y-axis.
+        array (:py:attr:`array_like`): The intensity map collected by the 2 dimensional detector.
+        x_start (:py:attr:`int`): Start point in x-axis.
+        x_end (:py:attr:`int`): End point in x-axis.
+        y_start (:py:attr:`int`): Start point in y-axis.
+        y_end (:py:attr:`int`): End point in y-axis.
 
     Returns:
-        (np.ndarray): A cropped intensity map.
+        :py:attr:`array_like`: A cropped intensity map.
     """
     cropped_array = array[x_start:x_end, y_start:y_end]
     return cropped_array
@@ -35,14 +34,13 @@ def crop_around_peak_2d(array, array_e=None, x_size=20, y_size=20):
     of dimensions [x_size, y_size].
 
     Args:
-        array (np.ndarray): Intensity map collected by the 2
-            dimensional detector.
-        array_e (np.ndarray): Uncertainty map collected by the 2-D detector.
-        x_size (int, optional): Size of the cropped image in x-axis. Defaults to 20.
-        y_size (int, optional): Size of the cropped image in y-axis. Defaults to 20. 
+        array (:py:attr:`array_like`): Intensity map collected by the 2 dimensional detector.
+        array_e (:py:attr:`array_like`): Uncertainty map collected by the 2-D detector.
+        x_size (:py:attr:`int`, optional): Size of the cropped image in x-axis. Defaults to :py:attr:`20`.
+        y_size (:py:attr:`int`, optional): Size of the cropped image in y-axis. Defaults to :py:attr:`20`. 
 
     Returns:
-        (np.ndarray): A cropped intensity map.
+        :py:attr:`array_like`: A cropped intensity map.
     """
     max_inten = np.unravel_index(np.argmax(array, axis=None), array.shape)
     half_x_size = int(x_size / 2)

islatu/image.py

@@ -1,8 +1,6 @@
 """
-The two-dimension detector generates images of the reflected
-intensity. 
-The purpose of this class is the investigation and manipulation
-of these images.
+The two-dimension detector generates images of the reflected intensity. 
+The purpose of this class is the investigation and manipulation of these images.
 """
 
 # Copyright (c) Andrew R. McCluskey
@@ -21,26 +19,19 @@ class Image:
     This class stores information about the detector images.
 
     Attributes:
-        file_path (str): File path for the image.
-        data (pd.DataFrame): Experimental data about the measurement.
-        metadata (dict): Metadata regarding the measurement.
-        array (array_like): The image described as an array.
-        bkg (uncertainties.cores.Variable): The background that was
-            subtracted from the image.
-        n_pixels (float): The width of the peak in number of pixels, used
-            to calculate an uncertainty in q on the detector.
+        file_path (:py:attr:`str`): File path for the image.
+        data (:py:class:`pandas.DataFrame`): Experimental data about the measurement.
+        metadata (:py:attr:`dict`): Metadata regarding the measurement.
+        array (:py:attr:`array_like`): The image described as an array.
+        bkg (:py:class:`uncertainties.cores.Variable`): The background that was subtracted from the image.
+        n_pixels (:py:attr:`float`): The width of the peak in number of pixels, used to calculate an uncertainty in q on the detector.
 
     Args:
-        file_path (str): The file path for the image.
-        data (pd.DataFrame, optional): Experimental data about the
-            measurement. Defaults to ``None``.
-        metadata (dict, optional): Metadata regarding the measurement.
-            Defaults to ``None``.
-        transpose (bool, optional): Should the data be rotated by 90 degrees?
-            Defaults to ``False``.
-        hot_pixel_threshold (int, optional): The number of counts above
-            which a pixel should be assessed to determine if it is hot.
-            Defaults to ``200000``.
+        file_path (:py:attr:`str`): The file path for the image.
+        data (:py:class:`pandas.DataFrame`, optional): Experimental data about the measurement. Defaults to :py:attr:`None`.
+        metadata (:py:attr:`dict`, optional): Metadata regarding the measurement. Defaults to :py:attr:`None`.
+        transpose (:py:attr:`bool`, optional): Should the data be rotated by 90 degrees? Defaults to :py:attr:`False`.
+        hot_pixel_threshold (:py:attr:`int`, optional): The number of counts above which a pixel should be assessed to determine if it is hot. Defaults to :py:attr:`200000`.
     """
 
     def __init__(
@@ -52,8 +43,7 @@ def __init__(
         hot_pixel_threshold=200000,
     ):
         """
-        Initialisation of the Image class, includes running hot pixel
-        check and assigning uncertainties.
+        Initialisation of the :py:class:`islatu.image.Image` class, includes running hot pixel check and assigning uncertainties.
         """
         self.file_path = file_path
         self.data = data
@@ -79,7 +69,7 @@ def nominal_values(self):
         Get the nominal values of the image array.
 
         Returns:
-            (np.ndarray): Nominal values of image.
+            :py:attr:`array_like`: Nominal values of image.
         """
         return unp.nominal_values(self.array)
 
@@ -89,7 +79,7 @@ def std_devs(self):
         Get the standard deviation values of the image array.
 
         Returns:
-            (np.ndarray): Standard deviation values of image.
+            :py:attr:`array_like`: Standard deviation values of image.
         """
         return unp.std_devs(self.array)
 
@@ -99,7 +89,7 @@ def n(self):
         Get the nominal values of the image array.
 
         Returns:
-            (np.ndarray): Nominal values of image.
+            :py:attr:`array_like`: Nominal values of image.
         """
         return unp.nominal_values(self.array)
 
@@ -109,7 +99,7 @@ def s(self):
         Get the standard deviation values of the image array.
 
         Returns:
-            (np.ndarray): Standard deviation values of image.
+            :py:attr:`array_like`: Standard deviation values of image.
         """
         return unp.std_devs(self.array)
 
@@ -119,7 +109,7 @@ def shape(self):
         Array shape
 
         Returns:
-            (tuple_of_int): The shape of the image.
+            :py:attr:`tuple` of :py:attr:`int`: The shape of the image.
         """
         return unp.nominal_values(self.array).shape
 
@@ -128,7 +118,7 @@ def show(self):
         Show the image.
 
         Return:
-            (mpl.Figure): Matplotlib imshow of array.
+            :py:class:`matplotlib.figure.Figure`: Matplotlib imshow of array.
         """
         return im.show(self.n)
 
@@ -137,7 +127,7 @@ def __repr__(self):
         Custom representation.
 
         Returns:
-            (np.ndarray): Image array.
+            :py:attr:`array_like`: Image array.
         """
         return self.array
 
@@ -146,7 +136,7 @@ def __str__(self):
         Custom string.
 
         Returns:
-            (np.ndarray): Image array.
+            :py:attr:`array_like`: Image array.
         """
         return self.array
 
@@ -155,8 +145,8 @@ def crop(self, crop_function, **kwargs):
         Perform an image crop based on some function.
 
         Args:
-            crop_function (callable): The function to crop the data.
-            **kwargs (dict): The function keyword arguments.
+            crop_function (:py:attr:`callable`): The function to crop the data.
+            **kwargs (:py:attr:`dict`): The crop function keyword arguments.
         """
         self.array = unp.uarray(*crop_function(self.n, self.s, **kwargs))
 
@@ -167,9 +157,8 @@ def background_subtraction(
         Perform a background subtraction based on some function.
 
         Args:
-            background_subtraction_function (callable): The function to model
-                the data and therefore remove the background.
-            **kwargs (dict): The function keyword arguments.
+            background_subtraction_function (:py:attr:`callable`): The function to model the data and therefore remove the background.
+            **kwargs (:py:attr:`dict`): The background substraction function keyword arguments.
         """
         bkg_popt, bkg_idx, pixel_idx = background_subtraction_function(
             self.n, self.s, **kwargs
@@ -183,8 +172,7 @@ def sum(self, axis=None):
         Perform a summation on the image
 
         Args:
-            axis (int, optional): The axis of the array to perform the
-                summation over.
+            axis (:py:attr:`int`, optional): The axis of the array to perform the summation over. Defaults to :py:attr:`None`.
         """
         return self.array.sum(axis)
 
@@ -194,13 +182,11 @@ def _find_hot_pixels(array, threshold=200000):
     Find some dead pixels and assign them with some local average value.
 
     Args:
-        array (np.ndarray): NumPy array describing the image.
-        threshold (int, optional): The number of counts above which a pixel
-            should be assessed to determine if it is hot. Defaults to
-            ``200000``.
+        array (:py:attr:`array_like`): NumPy array describing the image.
+        threshold (:py:attr:`int`, optional): The number of counts above which a pixel should be assessed to determine if it is hot. Defaults to :py:attr:`200000`.
 
     Returns:
-        (np.ndarray): NumPy array where hot pixels have been removed.
+        :py:attr:`array_like`: NumPy array where hot pixels have been removed.
     """
     sorted_array = np.sort(array.flatten())[::-1]
     for i in sorted_array:

islatu/io.py

@@ -1,5 +1,5 @@
 """
-Parsers for inputing experiental files.
+Parsers for inputing experimental files.
 """
 
 # Copyright (c) Andrew R. McCluskey
@@ -14,12 +14,12 @@ def i07_dat_parser(file_path):
     Parsing the .dat file from I07.
 
     Args:
-        (str): The ``.dat`` file to be read.
+        (:py:attr:`str`): The ``.dat`` file to be read.
 
     Returns:
-        (tuple): tuple containing:
-            - (dict): The metadata from the ``.dat`` file.
-            - (pd.DataFrame): The data from the ``.dat`` file.
+        :py:attr:`tuple`: Containing:
+            - :py:attr:`dict`: The metadata from the ``.dat`` file.
+            - :py:class:`pandas.DataFrame`: The data from the ``.dat`` file.
     """
     f_open = open(file_path, "r")
     # Neither the data nor the metadata are being read yet.