Refactor read_qdm_harvard function

AUTHORS.md

@@ -3,5 +3,6 @@
 The following people have made contributions to the project (in alphabetical
 order by last name) and are considered "The Magali developers":
 
+* [Yago Castro](https://github.com/YagoMCastro) - Universidade de São Paulo, Brazil (ORCID: 0009-0003-3884-9675)
 * [Gelson Ferreira](https://github.com/Souza-junior) - Universidade de São Paulo, Brazil (ORCID: 0000-0002-5695-4239)
 * [Leonardo Uieda](https://github.com/leouieda) - Universidade de São Paulo, Brazil (ORCID: 0000-0001-6123-9515)

magali/_io.py

@@ -35,26 +35,82 @@ def read_qdm_harvard(path):
         coordinates are in µm and magnetic field in nT.
     """
     contents = scipy.io.loadmat(path)
+    coordinates, data_names, bz = _extract_data_qdm_harvard(contents)
+    data = _create_qdm_harvard_grid(coordinates, data_names, bz, path)
+    return data
+
+
+def _extract_data_qdm_harvard(contents):
+    """
+    Define variables for generating a grid from QDM microscopy data.
+
+    Parameters
+    ----------
+    contents: dict
+        A dictionary containing essential parameters including spacing, Bz
+        component, and sensor sample distances.
+
+    Returns
+    -------
+    coordinates: tuple of arrays
+        Tuple of 1D arrays with coordinates of each point in the grid:
+        x, y, and z (vertical).
+    data_names : str or list
+        The name(s) of the data variables in the output grid. Ignored if data
+        is None.
+    bz : array
+        The Bz component in nT.
+    """
     # For some reason, the spacing is returned as an array with a single
     # value. That messes up operations below so get the only element out.
     spacing = contents["step"].ravel()[0] * METER_TO_MICROMETER
     bz = contents["Bz"] * TESLA_TO_NANOTESLA
     data_names = ["bz"]
-    shape = bz.shape
     sensor_sample_distance = contents["h"] * METER_TO_MICROMETER
+    shape = bz.shape
     x = np.arange(shape[1]) * spacing
     y = np.arange(shape[0]) * spacing
     z = np.full(shape, sensor_sample_distance)
-    data = vd.make_xarray_grid(
-        (x, y, z),
+    return (x, y, z), data_names, bz
+
+
+def _create_qdm_harvard_grid(coordinates, data_names, bz, path):
+    """
+    Creates QDM microscopy data in the Harvard group format.
+
+    This functions makes the xarray.Dataset and sets appropriate metadata.
+
+    Parameters
+    ----------
+    coordinates: tuple of arrays
+        Arrays with coordinates of each point in the grid. Each array must
+        contain values for a dimension in the order: easting, northing,
+        vertical, etc. All arrays must be 2d and need to have the same shape.
+        These coordinates can be generated through verde.grid_coordinates.
+    data_names : str or list
+        The name(s) of the data variables in the output grid. Ignored if data
+        is None.
+    path : str or pathlib.Path
+        Path to the input Matlab binary file.
+    bz : array
+        The Bz component in nT.
+
+    Returns
+    -------
+    qdm_data : xarray.Dataset
+        The magnetic field data as a regular grid with coordinates. The
+        coordinates are in µm and magnetic field in nT.
+    """
+    qdm_data = vd.make_xarray_grid(
+        coordinates,
         bz,
         data_names=data_names,
         dims=("y", "x"),
         extra_coords_names="z",
     )
-    data.x.attrs = {"units": "µm"}
-    data.y.attrs = {"units": "µm"}
-    data.z.attrs = {"long_name": "sensor sample distance", "units": "µm"}
-    data.bz.attrs = {"long_name": "vertical magnetic field", "units": "nT"}
-    data.attrs = {"file_name": str(path)}
-    return data
+    qdm_data.x.attrs = {"units": "µm"}
+    qdm_data.y.attrs = {"units": "µm"}
+    qdm_data.z.attrs = {"long_name": "sensor sample distance", "units": "µm"}
+    qdm_data.bz.attrs = {"long_name": "vertical magnetic field", "units": "nT"}
+    qdm_data.attrs = {"file_name": str(path)}
+    return qdm_data