Merge pull request #20 from Vital-Fernandez/dev

Innate 0.1.9

docs/source/conf.py

@@ -12,32 +12,52 @@
 release = '06/25/2024'
 
 # The full version, including alpha/beta/rc tags
-release = '0.1.8'
+release = '0.1.9'
 
 # -- Moving documentation building data functions ----------------------------
 
 import sys
 import os
-import shutil
 from pathlib import Path
 
-def all_but_ipynb(dir, contents):
-     result = []
-     for c in contents:
-         if os.path.isfile(os.path.join(dir, c)) and (not c.endswith(".py")):
-             result += [c]
-     return result
-#
-#
+# Adding library folder to the path to compile innate on the api autodoc commands
 _lib_path = Path(__file__).parents[2]/'src'
-_doc_folder = Path(__file__).parents[2]/'docs/source'
-_examples_path = Path(__file__).parents[2]/'docs/tutorials'
-_data_path = Path(__file__).parents[2]/'docs/data'
+sys.path.append(_lib_path.as_posix())
+
+def all_but_ipynb(dir, contents):
+    result = []
+    for c in contents:
+        if os.path.isfile(os.path.join(dir, c)) and (not c.endswith(".py")):
+            result += [c]
+    return result
+
+_lib_path = Path(__file__).parents[2] / 'src'
+_doc_folder = Path(__file__).parents[2] / 'docs/source'
+_examples_path = Path(__file__).parents[2] / 'docs/tutorials'
+_data_path = Path(__file__).parents[2] / 'docs/data'
 
 sys.path.append(_lib_path.as_posix())
 sys.path.append(_examples_path.as_posix())
 sys.path.append(_data_path.as_posix())
 
+# import os
+# import shutil
+#
+# def all_but_ipynb(dir, contents):
+#     result = []
+#     for c in contents:
+#         if os.path.isfile(os.path.join(dir, c)) and (not c.endswith(".py")):
+#             result += [c]
+#     return result
+#
+#
+# _lib_path = Path(__file__).parents[2]/'src'
+# _doc_folder = Path(__file__).parents[2]/'docs/source'
+# _examples_path = Path(__file__).parents[2]/'examples'
+# sys.path.append(_lib_path.as_posix())
+# sys.path.append(_examples_path.as_posix())
+
+
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
@@ -72,6 +92,6 @@ def all_but_ipynb(dir, contents):
 # shutil.rmtree(_doc_folder/'images', ignore_errors=True)
 # shutil.rmtree(_doc_folder/'inputs', ignore_errors=True)
 # shutil.rmtree(_doc_folder/'outputs', ignore_errors=True)
-#shutil.rmtree(_doc_folder/'data', ignore_errors=True)
-#shutil.rmtree(_doc_folder/'tutorials', ignore_errors=True)
-#shutil.copytree(_examples_path, _doc_folder, dirs_exist_ok=True)
+# shutil.rmtree(_doc_folder/'sample_data', ignore_errors=True)
+# shutil.rmtree(_doc_folder/'tutorials', ignore_errors=True)
+# shutil.copytree(_examples_path, _doc_folder, dirs_exist_ok=True)

docs/source/introduction/api.rst

@@ -1,8 +1,25 @@
-
-
-
 API
 ===
 
 :math:`\textsc{INNATE}` features a composite software design, utilizing instances of other classes to implement the target
-functionality.
+functionality. The image below shows a basic diagram with the library structure:
+
+.. image:: ../_static/library_structure.png
+    :align: center
+
+The next sections detail the functions attributes and their outputs:
+
+Inputs/outputs
+--------------
+
+.. autofunction:: innate.io.load_dataset
+
+.. autofunction:: innate.io.save_dataset
+
+
+Core objects
+------------
+
+.. autoclass:: innate.DataSet
+
+.. autofunction:: innate.DataSet.from_file

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "innate-stable"
-version = "0.1.8"
+version = "0.1.9"
 readme = "README.rst"
 requires-python = ">=3.10"
 license = {file = "COPYING"}

src/innate/config.toml

@@ -1,5 +1,5 @@
 [metadata]
-version = '0.1.8'
+version = '0.1.9'
 
 [parameter_labels]
 

src/innate/io.py

@@ -25,6 +25,39 @@ class InnateError(Exception):
 
 
 def load_dataset(fname: str):
+    """
+        Load the data grids and configuration from a digital file.
+
+        Parameters
+        ----------
+        fname : str
+            The file address or path of the file.
+
+        Returns
+        -------
+
+        A dictionary with the data arrays, a dictionary with the global grids configuration and a dictionary with the local grid configuration.
+            - For '.fits' files: (array_dict, common_cfg, local_cfg)
+            - For '.nc' files: (array_dict, common_cfg, local_cfg)
+
+        Raises
+        ------
+        InnateError
+            If no dataset file is found at the specified location.
+        KeyError
+            If the file extension is not recognized.
+
+        Notes
+        -----
+        This function checks the file extension and loads the dataset using the appropriate method:
+        - '.fits' files are loaded using `fits_file_load`.
+        - '.nc' files are loaded using `h5netcdf_file_load`.
+
+        Examples
+        --------
+        >>> data = load_dataset('data/file.fits')
+        >>> data = load_dataset('data/file.nc')
+        """
 
     # Check the file location
     fname = Path(fname)
@@ -49,14 +82,38 @@ def load_dataset(fname: str):
 def save_dataset(fname: str, grid_dict: dict, common_cfg: dict, custom_cfg: dict):
 
     """
-
-    :param fname:
-    :type str or Pathlib: path.Pathlib
-
-    :param cfg_dict:
-
-    :param grid_dict:
-
+    Save the data grids and configuration to a digital file.
+
+    Parameters
+    ----------
+    fname : str or pathlib.Path
+        The name of the file where the dataset will be saved.
+    grid_dict : dict
+        Dictionary containing the data grid to be saved.
+    common_cfg : dict
+        Dictionary containing common configuration parameters.
+    custom_cfg : dict
+        Dictionary containing custom configuration parameters.
+
+    Returns
+    -------
+    None
+
+    Raises
+    ------
+    KeyError
+        If the file extension is not recognized.
+
+    Notes
+    -----
+    This function checks the file extension and saves the dataset using the appropriate method:
+    - '.fits' files are saved using `fits_file_save`.
+    - '.nc' files are saved using `h5netcdf_file_save`.
+
+    Examples
+    --------
+    >>> save_dataset('data/output.fits', grid_dict, common_cfg, custom_cfg)
+    >>> save_dataset('data/output.nc', grid_dict, common_cfg, custom_cfg)
     """
 
     # Check the file location
@@ -65,7 +122,7 @@ def save_dataset(fname: str, grid_dict: dict, common_cfg: dict, custom_cfg: dict
 
     # Check there is input data
     if len(grid_dict) == 0:
-        raise InnateError(f'Output data grid does not contain any entry')
+        _logger.warning(f'Output dataset does not contain any grid entry')
 
     # Run the appropriate file saving workflow
     match ext:

src/innate/main.py

@@ -73,6 +73,36 @@ class DataSet(dict):
 
     def __init__(self, array_dict, common_cfg, local_cfg, **kwargs):
 
+        """
+        A class used to represent a Dataset, inheriting from Python's built-in dictionary.
+
+        This class is initialized with data arrays and configuration parameters,
+        and it unpacks these into the class dictionary.
+
+        Parameters
+        ----------
+        array_dict : dict
+            Dictionary containing data arrays.
+        common_cfg : dict
+            Dictionary containing common configuration parameters.
+        local_cfg : dict
+            Dictionary containing local configuration parameters.
+        **kwargs
+            Additional keyword arguments to be passed to the method.
+
+        Attributes
+        ----------
+        data_labels : None or list
+            Placeholder for data labels. Initialized as None.
+        shape_array : None or tuple
+            Placeholder for the shape of the data arrays. Initialized as None.
+
+        Methods
+        -------
+        _compile_grids(array_dict, common_cfg, local_cfg, **kwargs)
+            Unpacks the individual grids into the class dictionary.
+        """
+
         # Attributes
         self.data_labels = None
         self.shape_array = None
@@ -85,6 +115,33 @@ def __init__(self, array_dict, common_cfg, local_cfg, **kwargs):
     @classmethod
     def from_file(cls, fname, grid_cfg=None):
 
+        """
+        Creates a DataSet dictionarly-like object from an input file address.
+
+        Parameters
+        ----------
+        fname : str
+            The file address or path of the file containing the dataset.
+        grid_cfg : dict, optional
+            Configuration parameters for the dataset provided by the user. These values will overwrite common entries on
+             the fiel configuration parameter. Default is None.
+
+        Returns
+        -------
+        DataSet
+            A DataSet dictionarly-like object containing the scientific arrays, the data configuration and the
+            approximation techniques.
+
+        Notes
+        -----
+        This method loads and parses the input data from the specified file.
+        It updates the input configuration with the parameters provided by the user.
+
+        Examples
+        --------
+        >>> scientific_data = DataSet.from_file('data/file.txt', grid_cfg={'param': 'value'})
+        """
+
         # Load and parse the input data
         array_dict, common_cfg, local_cfg = load_dataset(fname)