Switch to Google docstrings (#101)

Zethson · web-flow · commit 3f2a94dae2d6 · 2025-04-15T18:09:00.000+02:00
* Switch to Google docstrings

Signed-off-by: zethson &lt;lukas.heumos@posteo.net&gt;

* lazy vitessce

Signed-off-by: zethson &lt;lukas.heumos@posteo.net&gt;

* spec0

Signed-off-by: zethson &lt;lukas.heumos@posteo.net&gt;

* moar docstring fixes

Signed-off-by: zethson &lt;lukas.heumos@posteo.net&gt;

* fix batch_size

Signed-off-by: zethson &lt;lukas.heumos@posteo.net&gt;

* remove wrong gitignore entry

Signed-off-by: zethson &lt;lukas.heumos@posteo.net&gt;

* fix docs

Signed-off-by: zethson &lt;lukas.heumos@posteo.net&gt;

* fix widgets

Signed-off-by: zethson &lt;lukas.heumos@posteo.net&gt;

* fix widgets

Signed-off-by: zethson &lt;lukas.heumos@posteo.net&gt;

---------

Signed-off-by: zethson &lt;lukas.heumos@posteo.net&gt;
diff --git a/.github/workflows/test.yaml b/.github/workflows/test.yaml
@@ -26,11 +26,11 @@ jobs:
       matrix:
         include:
           - os: ubuntu-latest
-            python: "3.10"
+            python: "3.11"
           - os: ubuntu-latest
-            python: "3.12"
+            python: "3.13"
           - os: ubuntu-latest
-            python: "3.12"
+            python: "3.13"
             pip-flags: "--pre"
             name: PRE-RELEASE DEPENDENCIES
 
diff --git a/.gitignore b/.gitignore
@@ -18,3 +18,5 @@ __pycache__/
 # docs
 /docs/generated/
 /docs/_build/
+
+ehrapy_data
diff --git a/docs/conf.py b/docs/conf.py
@@ -74,8 +74,8 @@
 autosummary_generate = True
 autodoc_member_order = "groupwise"
 default_role = "literal"
-napoleon_google_docstring = False
-napoleon_numpy_docstring = True
+napoleon_google_docstring = True
+napoleon_numpy_docstring = False
 napoleon_include_init_with_doc = False
 napoleon_use_rtype = True  # having a separate entry generally helps readability
 napoleon_use_param = True
@@ -106,6 +106,7 @@
     "h5py": ("https://docs.h5py.org/en/latest", None),
     "scanpy": ("https://scanpy.readthedocs.io/en/stable", None),
     "numpy": ("https://numpy.org/doc/stable", None),
+    "torch": ("https://pytorch.org/docs/main/", None),
     "scipy": ("https://docs.scipy.org/doc/scipy", None),
     "pandas": ("https://pandas.pydata.org/docs", None),
     "zarr": ("https://zarr.readthedocs.io/en/stable", None),
diff --git a/docs/notebooks/omop_ml.ipynb b/docs/notebooks/omop_ml.ipynb
@@ -429,7 +429,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "dataset = ed.tl.omop.EHRDataset(con, edata, batch_size=5, idxs=None)"
+    "dataset = ed.tl.omop.EHRDataset(con, edata, idxs=None)"
    ]
   },
   {
diff --git a/docs/notebooks/widgets.py b/docs/notebooks/widgets.py
@@ -5,12 +5,11 @@ def create_single_option_widget(title_text: str, options: list[str]):
     """Create a single-option selection widget (RadioButtons).
 
     Args:
-        title_text (str): The title displayed above the radio buttons.
-        options (list[str]): List of strings representing the radio button options.
-        default_value (str): The default selected value.
+        title_text: The title displayed above the radio buttons.
+        options: List of strings representing the radio button options.
+        default_value: The default selected value.
 
-    Returns
-    -------
+    Returns:
         tuple: A VBox containing the UI elements and the RadioButtons widget.
     """
     title = widgets.HTML(f"<h3>{title_text}</h3>")
@@ -25,11 +24,10 @@ def create_multiple_options_widget(title_text: str, options: list[str]):
     """Create a multiple-option selection widget (SelectMultiple).
 
     Args:
-        title_text (str): The title displayed above the selection box.
-        options (list[str]): List of strings representing the options.
+        title_text: The title displayed above the selection box.
+        options: List of strings representing the options.
 
-    Returns
-    -------
+    Returns:
         tuple: A VBox containing the UI elements and the SelectMultiple widget.
     """
     title = widgets.HTML(f"<h3 style='color: #333; font-family: Arial, sans-serif;'>{title_text}</h3>")
diff --git a/pyproject.toml b/pyproject.toml
@@ -75,7 +75,7 @@ optional-dependencies.torch = [
 
 optional-dependencies.vitessce = [
   "vitessce[all]>=3.4", # the actual dependency
-  "zarr<3",             # vitessce does not support zarr>=3
+  "zarr>=2.18.7,<3",    # vitessce does not support zarr>=3
 ]
 # https://docs.pypi.org/project_metadata/#project-urls
 urls.Documentation = "https://ehrdata.readthedocs.io/"
@@ -133,7 +133,7 @@ lint.ignore = [
 lint.per-file-ignores."*/__init__.py" = [ "F401" ]
 lint.per-file-ignores."docs/*" = [ "I" ]
 lint.per-file-ignores."tests/*" = [ "D" ]
-lint.pydocstyle.convention = "numpy"
+lint.pydocstyle.convention = "google"
 
 [tool.pytest.ini_options]
 testpaths = [ "tests" ]
diff --git a/src/ehrdata/_omop_utils.py b/src/ehrdata/_omop_utils.py
@@ -6,14 +6,12 @@
 def get_table_catalog_dict(version: Literal["5.4"] = "5.4"):
     """Get the table catalog dictionary of the OMOP CDM.
 
-    Parameters
-    ----------
-    version
-        The version of the OMOP CDM. Currently, only 5.4 is supported.
+    Args:
+        version:
+            The version of the OMOP CDM. Currently, only 5.4 is supported.
 
-    Returns
-    -------
-        Dictionary: a dictionary of the table catalog. The key is the category of the table, and the value is a list of table names
+    Returns:
+        A dictionary of the table catalog. The key is the category of the table, and the value is a list of table names.
     """
     table_catalog_dict = {}
     table_catalog_dict["Clinical data"] = [
diff --git a/src/ehrdata/core/_compat.py b/src/ehrdata/core/_compat.py
@@ -1,4 +1,4 @@
-def lazy_import_torch():
+def lazy_import_torch() -> None:
     try:
         import torch
 
diff --git a/src/ehrdata/core/ehrdata.py b/src/ehrdata/core/ehrdata.py
@@ -19,40 +19,27 @@
 
 
 class EHRData(AnnData):
-    """EHRData object.
+    """Model two and three dimensional electronic health record data.
 
-    Inherits `__init__` parameters, methods, and properties from :class:`~anndata.AnnData`.
+    Extends :class:`~anndata.AnnData` to further support regular and irregular time-series data.
 
-    Parameters
-    ----------
-        X
-            A #observations × #variables data matrix. A view of the data is used if the
+    Args:
+        X: A #observations × #variables data matrix. A view of the data is used if the
             data type matches, otherwise, a copy is made.
-        r
-            A #observations × #variables × #timesteps data array. A view of the data is used if the
-            data type matches, otherwise, a copy is made.
-        obs
-            Key-indexed one-dimensional observations annotation of length #observations.
-        var
-            Key-indexed one-dimensional variables annotation of length #variables.
-        t
-            Key-indexed one-dimensional time annotation of length #timesteps.
-        uns
-            Key-indexed unstructured annotation.
-        obsm
-            Key-indexed multi-dimensional observations annotation of length #observations.
-            If passing a :class:`~numpy.ndarray`, it needs to have a structured datatype.
-        varm
-            Key-indexed multi-dimensional variables annotation of length #variables.
-            If passing a :class:`~numpy.ndarray`, it needs to have a structured datatype.
-        layers
-            Key-indexed multi-dimensional arrays aligned to dimensions of `X`.
-        shape
-            Shape tuple (#observations, #variables). Can only be provided if `X` is `None`.
-        filename
-            Name of backing file. See :class:`h5py.File`.
-        filemode
-            Open mode of backing file. See :class:`h5py.File`.
+        r: A #observations × #variables × #timesteps data array. A view of the data is used if
+            the data type matches, otherwise, a copy is made.
+        obs: Key-indexed one-dimensional observations annotation of length #observations.
+        var: Key-indexed one-dimensional variables annotation of length #variables.
+        t: Key-indexed one-dimensional time annotation of length #timesteps.
+        uns: Key-indexed unstructured annotation.
+        obsm: Key-indexed multi-dimensional observations annotation of length #observations.
+            If passing a :class:`numpy.ndarray`, it needs to have a structured datatype.
+        varm: Key-indexed multi-dimensional variables annotation of length #variables.
+            If passing a :class:`numpy.ndarray`, it needs to have a structured datatype.
+        layers: Key-indexed multi-dimensional arrays aligned to dimensions of `X`.
+        shape: Shape tuple (#observations, #variables). Can only be provided if `X` is None.
+        filename: Name of backing file. See :class:`h5py.File`.
+        filemode: Open mode of backing file. See :class:`h5py.File`.
     """
 
     _t: pd.DataFrame | None
@@ -174,20 +161,14 @@ def from_adata(
     ) -> EHRData:
         """Create an EHRData object from an AnnData object.
 
-        Parameters
-        ----------
-        adata
-            Annotated data object.
-        r
-            3-Dimensional tensor, see :attr:`r`.
-        t
-            Time dataframe for describing third axis, see :attr:`t`.
-        tidx
-            A slice for the 3rd dimension :attr:`r`. Usually, this will be None here.
-
-        Returns
-        -------
-        An EHRData object.
+        Args:
+            adata: Annotated data object.
+            r: 3-Dimensional tensor, see r attribute.
+            t: Time dataframe for describing third axis, see t attribute.
+            tidx: A slice for the 3rd dimension r. Usually, this will be None here.
+
+        Returns:
+            An EHRData object extending the AnnData object.
         """
         instance = cls(shape=adata.shape)
 
@@ -371,14 +352,11 @@ def __repr__(self) -> str:
     def __getitem__(self, index: Index | None) -> EHRData:
         """Slice the EHRData object along 1–3 axes.
 
-        Parameters
-        ----------
-        index
-            1D, 2D, or 3D index.
+        Args:
+            index: 1D, 2D, or 3D index.
 
-        Returns
-        -------
-        An EHRData view object.
+        Returns:
+            An EHRData view object.
         """
         oidx, vidx, tidx = self._unpack_index(index)
         adata_sliced = super().__getitem__((oidx, vidx))
diff --git a/src/ehrdata/dt/dataloader.py b/src/ehrdata/dt/dataloader.py
@@ -23,7 +23,9 @@ def download(
 
     Args:
         url: URL to download.
-        download_path: Where the data should be downloaded to.
+        saving_path: Where the data should be downloaded to.
+        block_size: Download block size.
+        overwrite: Whether to overwrite existing data.
     """
     # note: tar.gz has to be before gz for the _remove_archive_extension function to remove the entire extension
     compression_formats = ["tar.gz", "zip", "tar", "gz", "bz", "xz"]
diff --git a/src/ehrdata/dt/datasets.py b/src/ehrdata/dt/datasets.py
@@ -44,25 +44,19 @@ def _setup_eunomia_datasets(
 def mimic_iv_omop(backend_handle: DuckDBPyConnection, data_path: Path | None = None) -> None:
     """Loads the MIMIC-IV demo data in the OMOP Common Data model.
 
-    This function loads the MIMIC-IV demo dataset from its `physionet repository <https://physionet.org/content/mimic-iv-demo-omop/0.9/#files-panel>`_.
+    Loads the MIMIC-IV demo dataset from its `physionet repository <https://physionet.org/content/mimic-iv-demo-omop/0.9/#files-panel>`_.
     See also this link for more details.
 
     DOI https://doi.org/10.13026/2d25-8g07.
 
-    Parameters
-    ----------
-    backend_handle
-        A handle to the backend which shall be used. Only duckdb connection supported at the moment.
-    data_path
-        Path to the tables. If the path exists, the data is loaded from there. Else, the data is downloaded.
+    Args:
+        backend_handle: A handle to the backend which shall be used. Only duckdb connection supported at the moment.
+        data_path: Path to the tables. If the path exists, the data is loaded from there. Else, the data is downloaded.
 
-    Returns
-    -------
-    Returns nothing, adds the tables to the backend via the handle.
+    Returns:
+        Nothing. Adds the tables to the backend via the handle.
 
-    Examples
-    --------
-        >>> import ehrapy as ep
+    Examples:
         >>> import ehrdata as ed
         >>> import duckdb
         >>> con = duckdb.connect()
@@ -85,23 +79,17 @@ def mimic_iv_omop(backend_handle: DuckDBPyConnection, data_path: Path | None = N
 def gibleed_omop(backend_handle: DuckDBPyConnection, data_path: Path | None = None) -> None:
     """Loads the GiBleed dataset in the OMOP Common Data model.
 
-    This function loads the GIBleed dataset from the `EunomiaDatasets repository <https://github.com/OHDSI/EunomiaDatasets>`_.
+    Loads the GIBleed dataset from the `EunomiaDatasets repository <https://github.com/OHDSI/EunomiaDatasets>`_.
     More details: https://github.com/OHDSI/EunomiaDatasets/tree/main/datasets/GiBleed.
 
-    Parameters
-    ----------
-    backend_handle
-        A handle to the backend which shall be used. Only duckdb connection supported at the moment.
-    data_path
-        Path to the tables. If the path exists, the data is loaded from there. Else, the data is downloaded.
+    Args:
+        backend_handle: A handle to the backend which shall be used. Only duckdb connection supported at the moment.
+        data_path: Path to the tables. If the path exists, the data is loaded from there. Else, the data is downloaded.
 
-    Returns
-    -------
-    Returns nothing, adds the tables to the backend via the handle.
+    Returns:
+        Nothing. Adds the tables to the backend via the handle.
 
-    Examples
-    --------
-        >>> import ehrapy as ep
+    Examples:
         >>> import ehrdata as ed
         >>> import duckdb
         >>> con = duckdb.connect()
@@ -127,19 +115,14 @@ def synthea27nj_omop(backend_handle: DuckDBPyConnection, data_path: Path | None
     This function loads the Synthea27Nj dataset from the `EunomiaDatasets repository <https://github.com/OHDSI/EunomiaDatasets>`_.
     More details: https://github.com/OHDSI/EunomiaDatasets/tree/main/datasets/Synthea27Nj.
 
-    Parameters
-    ----------
-    backend_handle
-        A handle to the backend which shall be used. Only duckdb connection supported at the moment.
-    data_path
-        Path to the tables. If the path exists, the data is loaded from there. Else, the data is downloaded.
+    Args:
+        backend_handle: A handle to the backend which shall be used. Only duckdb connection supported at the moment.
+        data_path: Path to the tables. If the path exists, the data is loaded from there. Else, the data is downloaded.
 
-    Returns
-    -------
-    Returns nothing, adds the tables to the backend via the handle.
+    Returns:
+        Nothing. Adds the tables to the backend via the handle.
 
-    Examples
-    --------
+    Examples:
         >>> import ehrapy as ep
         >>> import ehrdata as ed
         >>> import duckdb
@@ -196,27 +179,22 @@ def physionet2012(
     A simple deviation is that the tensor in ehrdata is of shape n_obs x n_vars x n_intervals (with defaults, 3000x37x48) while the tensor in PyPOTS is of shape n_obs x n_intervals x n_vars (3000x48x37).
     The tensor stored in .r is hence also fully compatible with the PyPOTS package, as the .r tensor of EHRData objects generally is.
 
-    Parameters
-    ----------
-    data_path
-        Path to the raw data. If the path exists, the data is loaded from there. Else, the data is downloaded.
-    interval_length_number
-        Numeric value of the length of one interval.
-    interval_length_unit
-        Unit belonging to the interval length.
-    num_intervals
-        Number of intervals.
-    aggregation_strategy
-        Aggregation strategy for the time series data when multiple measurements for a person's parameter within a time interval is available. Available are 'first' and 'last', as used in `pd.DataFrame.drop_duplicates <https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.drop_duplicates.html>`_.
-    drop_samples
-        Samples to drop from the dataset (indicate their RecordID).
-
-    Returns
-    -------
-    Returns a the processed physionet2012 dataset in an EHRData object. The raw data is also downloaded, stored and available under the data_path.
-
-    Examples
-    --------
+    Args:
+       data_path: Path to the raw data. If the path exists, the data is loaded from there.
+           Else, the data is downloaded.
+       interval_length_number: Numeric value of the length of one interval.
+       interval_length_unit: Unit belonging to the interval length.
+       num_intervals: Number of intervals.
+       aggregation_strategy: Aggregation strategy for the time series data when multiple
+           measurements for a person's parameter within a time interval is available.
+           Available are 'first' and 'last', as used in pandas.DataFrame.drop_duplicates.
+       drop_samples: Samples to drop from the dataset (indicate their RecordID).
+
+    Returns:
+        Returns a the processed physionet2012 dataset in an EHRData object.
+        The raw data is also downloaded, stored and available under the ``data_path``.
+
+    Examples:
         >>> import ehrapy as ep
         >>> import ehrdata as ed
         >>> edata = ed.dt.physionet_2012()
diff --git a/src/ehrdata/io/omop/omop.py b/src/ehrdata/io/omop/omop.py
diff --git a/src/ehrdata/pl/vitessce.py b/src/ehrdata/pl/vitessce.py
diff --git a/src/ehrdata/tl/omop/_dataset.py b/src/ehrdata/tl/omop/_dataset.py
diff --git a/tests/tl/test_ehrdataset.py b/tests/tl/test_ehrdataset.py

Original file line number	Diff line number	Diff line change
`@@ -429,7 +429,7 @@`
`429`	`429`	`"metadata": {},`
`430`	`430`	`"outputs": [],`
`431`	`431`	`"source": [`
`432`		`- "dataset = ed.tl.omop.EHRDataset(con, edata, batch_size=5, idxs=None)"`
	`432`	`+ "dataset = ed.tl.omop.EHRDataset(con, edata, idxs=None)"`
`433`	`433`	`]`
`434`	`434`	`},`
`435`	`435`	`{`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-def lazy_import_torch():`
	`1`	`+def lazy_import_torch() -> None:`
`2`	`2`	`try:`
`3`	`3`	`import torch`
`4`	`4`