Feature/irregular_structure_and_operations

docs/modules/representation.rst

@@ -85,6 +85,28 @@ methods.
 
    skfda.representation.basis.Basis
 
+
+Irregular representation
+------------------------
+
+In practice, most functional datasets do not contain functions evaluated
+uniformly over a fixed grid. In other words, it is paramount to be able
+to represent irregular functional data.
+
+While the FDataGrid class could support these kind of datasets, it is
+inefficient to store a complete grid with low data density. Furthermore,
+there are specific methods that can be applied to irregular data in order
+to obtain, among other things, a better convesion to basis representation.
+
+The FDataIrregular class provides the functionality which suits these purposes.
+
+
+.. autosummary::
+   :toctree: autosummary
+
+   skfda.representation.irregular.FDataIrregular
+
+
 Generic representation
 ----------------------
 

skfda/datasets/__init__.py

@@ -20,6 +20,7 @@
             "fetch_tecator",
             "fetch_ucr",
             "fetch_weather",
+            "fetch_bone_density",
         ],
         "_samples_generators": [
             "make_gaussian",

skfda/datasets/_real_datasets.py

@@ -5,13 +5,13 @@
 
 import numpy as np
 import pandas as pd
+import rdata
 from pandas import DataFrame, Series
 from sklearn.utils import Bunch
 from typing_extensions import Literal
 
-import rdata
-
 from ..representation import FDataGrid
+from ..representation.irregular import FDataIrregular
 from ..typing._numpy import NDArrayFloat, NDArrayInt
 
 
@@ -174,7 +174,7 @@ def fetch_ucr(
     return_X_y: bool = False,
     **kwargs: Any,
 ) -> Bunch | Tuple[FDataGrid, NDArrayInt]:
-    """
+    r"""
     Fetch a dataset from the UCR/UEA repository.
 
     The UCR/UEA Time Series Classification repository, hosted at
@@ -185,6 +185,7 @@ def fetch_ucr(
 
     Args:
         name: Dataset name.
+        return_X_y: Return tuple (data, target)
         kwargs: Additional parameters for the function
             :func:`skdatasets.repositories.ucr.fetch`.
 
@@ -261,7 +262,7 @@ def _fetch_fda_usc(name: str) -> Any:
     Acoustic-Phonetic Continuous Speech Corpus, NTIS, US Dept of Commerce)
     which is a widely used resource for research in speech recognition. A
     dataset was formed by selecting five phonemes for
-    classification based on digitized speech from this database.   
+    classification based on digitized speech from this database.
     phonemes are transcribed as follows: "sh" as in "she", "dcl" as in
     "dark", "iy" as the vowel in "she", "aa" as the vowel in "dark", and
     "ao" as the first vowel in "water". From continuous speech of 50 male
@@ -1563,3 +1564,92 @@ def fetch_mco(
         cite=":footcite:p:`ruiz-meana++_2003_cariporide`",
         bibliography=".. footbibliography::",
     ) + _param_descr
+
+
+def _fetch_loon_data(name: str) -> Any:
+    return _fetch_cran_no_encoding_warning(
+        name,
+        "loon.data",
+        version="0.1.3",
+    )
+
+
+_bone_density_descr = """
+    The Bone Density dataset is a study of bone density
+    in boys and girls aged 8-17. It contains data from 423
+    individuals, measured irregularly in different times,
+    with an average of ~3 points per individual.
+
+    References:
+        https://cran.r-project.org/package=loon.data
+        Laura K. Bachrach, Trevor Hastie, May-Choo Wang,
+            Balasubramanian Narasimhan, and Robert Marcus (1999)
+            "Bone Mineral Acquisition in Healthy Asian, Hispanic, Black
+            and Caucasian Youth. A Longitudinal Study",
+            J Clin Endocrinol Metab, 84, 4702-12.
+        Trevor Hastie, Robert Tibshirani, and Jerome Friedman (2009)
+            "The Elements of Statistical Learning",
+            2nd Edition, Springer New York <doi:10.1007/978-0-387-84858-7>
+
+"""
+
+
+def fetch_bone_density(
+    return_X_y: bool = False,
+    as_frame: bool = False,
+) -> Bunch | Tuple[FDataGrid, NDArrayInt] | Tuple[DataFrame, Series]:
+    """
+    Load the Bone Density dataset. This is an irregular dataset.
+
+    The data is obtained from the R package 'loon.data', which compiles several
+    irregular datasets. Sources to be determined.
+    """
+    descr = _bone_density_descr
+    frame = None
+
+    raw_dataset = _fetch_loon_data("bone_ext")
+
+    data = raw_dataset["bone_ext"]
+
+    curve_name = "idnum"
+    argument_name = "age"
+    target_name = "sex"
+    coordinate_name = "spnbmd"
+
+    curves = FDataIrregular.from_dataframe(
+        data,
+        id_column=curve_name,
+        argument_columns=argument_name,
+        coordinate_columns=coordinate_name,
+        argument_names=[argument_name],
+        coordinate_names=[coordinate_name],
+        dataset_name="bone_ext",
+    )
+
+    target = pd.Series(
+        data.drop_duplicates(subset=["idnum"])[target_name],
+        name="group",
+    )
+
+    feature_name = curves.dataset_name.lower()
+    target_names = target.values.tolist()
+
+    if as_frame:
+        curves = pd.DataFrame({feature_name: curves})
+        target_as_frame = target.reset_index(drop=True).to_frame()
+        frame = pd.concat([curves, target_as_frame], axis=1)
+    else:
+        target = target.values.codes
+
+    if return_X_y:
+        return curves, target
+
+    return Bunch(
+        data=curves,
+        target=target,
+        frame=frame,
+        categories={},
+        feature_names=[argument_name],
+        target_names=target_names,
+        DESCR=descr,
+    )