From 1f091e71e920d715fa3c9804a5305011b3b7fe44 Mon Sep 17 00:00:00 2001 From: Ahmet Nihat Simsek Date: Wed, 25 Oct 2023 16:14:20 +0200 Subject: [PATCH] Doc: add docstring to (sub-) packages and modules --- docs/api.rst | 21 +++++++++++---------- siibra/features/__init__.py | 2 +- siibra/features/anchor.py | 2 ++ siibra/features/connectivity/__init__.py | 1 + siibra/features/dataset/__init__.py | 1 + siibra/features/dataset/ebrains.py | 3 +-- siibra/features/feature.py | 1 + siibra/features/image/image.py | 1 + siibra/features/tabular/tabular.py | 1 + siibra/livequeries/__init__.py | 1 + siibra/livequeries/allen.py | 1 + siibra/livequeries/bigbrain.py | 1 + siibra/livequeries/ebrains.py | 1 + siibra/livequeries/query.py | 1 + siibra/locations/__init__.py | 1 + siibra/locations/boundingbox.py | 1 + siibra/locations/location.py | 2 +- siibra/locations/point.py | 1 + siibra/locations/pointset.py | 1 + siibra/retrieval/__init__.py | 1 + siibra/retrieval/cache.py | 1 + siibra/retrieval/datasets.py | 2 +- siibra/retrieval/exceptions/__init__.py | 16 ++++++++++++++++ siibra/retrieval/repositories.py | 1 + siibra/retrieval/requests.py | 1 + siibra/vocabularies/__init__.py | 2 +- siibra/volumes/gifti.py | 1 + siibra/volumes/neuroglancer.py | 1 + siibra/volumes/nifti.py | 1 + 29 files changed, 55 insertions(+), 16 deletions(-) diff --git a/docs/api.rst b/docs/api.rst index c7e932cf5..8930d3774 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -6,11 +6,13 @@ API Documentation ================= +The class and package diagrams can be found at the `developer documentation`. + :mod:`Siibra` ==================== -Main Packages -============= +Main Packages and Modules +========================= .. autopackagesummary:: siibra :toctree: _autosummary @@ -24,23 +26,22 @@ Volumes .. autopackagesummary:: siibra.volumes :toctree: _autosummary -Features -======== -.. autopackagesummary:: siibra.features - :toctree: _autosummary - Locations ========= .. autopackagesummary:: siibra.locations :toctree: _autosummary -Miscellaneous Helpers -===================== +Features +======== +.. autopackagesummary:: siibra.features + :toctree: _autosummary + Live queries ------------ .. autopackagesummary:: siibra.livequeries :toctree: _autosummary + Retrieval ---------- +========= .. autopackagesummary:: siibra.retrieval :toctree: _autosummary diff --git a/siibra/features/__init__.py b/siibra/features/__init__.py index dcfc6fcb8..84c5d5d14 100644 --- a/siibra/features/__init__.py +++ b/siibra/features/__init__.py @@ -12,7 +12,7 @@ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. - +"""Multimodal data features types and query mechanisms.""" from . import ( connectivity, diff --git a/siibra/features/anchor.py b/siibra/features/anchor.py index df8ee82c1..ce20cc5c4 100644 --- a/siibra/features/anchor.py +++ b/siibra/features/anchor.py @@ -12,6 +12,7 @@ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. +"""Handles the relation between study targets and AtlasConcepts.""" from ..commons import logger, Species @@ -29,6 +30,7 @@ AnatomicalAssignment = RelationAssignment[Union[Region, Location]] + class AnatomicalAnchor: """ Anatomical anchor to an atlas region, diff --git a/siibra/features/connectivity/__init__.py b/siibra/features/connectivity/__init__.py index 2766fe3df..1e287313e 100644 --- a/siibra/features/connectivity/__init__.py +++ b/siibra/features/connectivity/__init__.py @@ -12,6 +12,7 @@ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. +"""Multimodal data features concerning connectivity data.""" from .functional_connectivity import FunctionalConnectivity from .streamline_counts import StreamlineCounts diff --git a/siibra/features/dataset/__init__.py b/siibra/features/dataset/__init__.py index 8128ffb7e..663ccce6c 100644 --- a/siibra/features/dataset/__init__.py +++ b/siibra/features/dataset/__init__.py @@ -12,5 +12,6 @@ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. +"""Non-preconfigured data features published as datasets.""" from .ebrains import EbrainsDataFeature diff --git a/siibra/features/dataset/ebrains.py b/siibra/features/dataset/ebrains.py index 40c9d26e5..a9ce1b228 100644 --- a/siibra/features/dataset/ebrains.py +++ b/siibra/features/dataset/ebrains.py @@ -12,8 +12,7 @@ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. - -# simple data features anchored to a point in space +"""Non-preconfigured data features hosted at EBRAINS.""" from zipfile import ZipFile from .. import anchor as _anchor diff --git a/siibra/features/feature.py b/siibra/features/feature.py index 223e6f202..9bceb9a1c 100644 --- a/siibra/features/feature.py +++ b/siibra/features/feature.py @@ -12,6 +12,7 @@ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. +"""Handles multimodal data features and related queries.""" from . import anchor as _anchor diff --git a/siibra/features/image/image.py b/siibra/features/image/image.py index 1f5000242..bd37deba5 100644 --- a/siibra/features/image/image.py +++ b/siibra/features/image/image.py @@ -12,6 +12,7 @@ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. +"""Multimodal data features in volume or image formats.""" from zipfile import ZipFile from .. import feature diff --git a/siibra/features/tabular/tabular.py b/siibra/features/tabular/tabular.py index 4453acf7c..b51f381e0 100644 --- a/siibra/features/tabular/tabular.py +++ b/siibra/features/tabular/tabular.py @@ -12,6 +12,7 @@ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. +"""Multimodal data features in tabular formats.""" from zipfile import ZipFile from .. import feature diff --git a/siibra/livequeries/__init__.py b/siibra/livequeries/__init__.py index b12953267..7670425f9 100644 --- a/siibra/livequeries/__init__.py +++ b/siibra/livequeries/__init__.py @@ -12,6 +12,7 @@ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. +"""Feature queries requiring live query or on-the-fly calculations.""" from .allen import AllenBrainAtlasQuery from .bigbrain import LayerwiseBigBrainIntensityQuery, BigBrainProfileQuery diff --git a/siibra/livequeries/allen.py b/siibra/livequeries/allen.py index 867889c49..7fe6eecd4 100644 --- a/siibra/livequeries/allen.py +++ b/siibra/livequeries/allen.py @@ -12,6 +12,7 @@ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. +"""Query Allen Human Brain Atlas microarray data in specified volume.""" from .query import LiveQuery diff --git a/siibra/livequeries/bigbrain.py b/siibra/livequeries/bigbrain.py index e45f8d983..a878e3c10 100644 --- a/siibra/livequeries/bigbrain.py +++ b/siibra/livequeries/bigbrain.py @@ -12,6 +12,7 @@ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. +"""Matches BigBrain intesity profiles extracted by Wagstyl et al. to volumes.""" from . import query diff --git a/siibra/livequeries/ebrains.py b/siibra/livequeries/ebrains.py index e157e74f7..8e431a4b9 100644 --- a/siibra/livequeries/ebrains.py +++ b/siibra/livequeries/ebrains.py @@ -12,6 +12,7 @@ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. +"""Query data features published as Ebrains datasets with AtlasConcepts""" from ..features.dataset import ebrains as _ebrains from . import query diff --git a/siibra/livequeries/query.py b/siibra/livequeries/query.py index c88cd7a50..dee991f3a 100644 --- a/siibra/livequeries/query.py +++ b/siibra/livequeries/query.py @@ -12,6 +12,7 @@ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. +"""Handles feature queries that rely on live or on-the-fly calculations.""" from ..commons import logger from ..features.feature import Feature diff --git a/siibra/locations/__init__.py b/siibra/locations/__init__.py index c441f068a..94f712787 100644 --- a/siibra/locations/__init__.py +++ b/siibra/locations/__init__.py @@ -12,6 +12,7 @@ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. +"""Handles spatial concepts and spatial operation like warping between spaces.""" from .location import WholeBrain from .point import Point diff --git a/siibra/locations/boundingbox.py b/siibra/locations/boundingbox.py index 8d7f30648..c43f72d0c 100644 --- a/siibra/locations/boundingbox.py +++ b/siibra/locations/boundingbox.py @@ -12,6 +12,7 @@ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. +"""A box defined by two farthest corner coordinates on a specific space.""" from . import point, pointset, location, boundingbox diff --git a/siibra/locations/location.py b/siibra/locations/location.py index 6be5df500..ee3201315 100644 --- a/siibra/locations/location.py +++ b/siibra/locations/location.py @@ -12,7 +12,7 @@ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. - +"""Concpets that have primarily spatial meaning.""" import numpy as np from abc import ABC, abstractmethod diff --git a/siibra/locations/point.py b/siibra/locations/point.py index 25e4e609f..5989eef0b 100644 --- a/siibra/locations/point.py +++ b/siibra/locations/point.py @@ -12,6 +12,7 @@ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. +"""Singular coordinate defined on a space, possibly with an uncertainty.""" from . import location, boundingbox, pointset from ..commons import logger diff --git a/siibra/locations/pointset.py b/siibra/locations/pointset.py index 9bde52940..7d00c10e2 100644 --- a/siibra/locations/pointset.py +++ b/siibra/locations/pointset.py @@ -12,6 +12,7 @@ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. +"""A set of coordinates on a reference space.""" from . import location, point, boundingbox diff --git a/siibra/retrieval/__init__.py b/siibra/retrieval/__init__.py index 5c993e57f..4d4798221 100644 --- a/siibra/retrieval/__init__.py +++ b/siibra/retrieval/__init__.py @@ -12,6 +12,7 @@ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. +"""File digestion and caching.""" from .repositories import ( GitlabConnector, diff --git a/siibra/retrieval/cache.py b/siibra/retrieval/cache.py index ab93a7f25..73946b6aa 100644 --- a/siibra/retrieval/cache.py +++ b/siibra/retrieval/cache.py @@ -12,6 +12,7 @@ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. +"""Maintaining and hadnling caching files on disk.""" import hashlib import os diff --git a/siibra/retrieval/datasets.py b/siibra/retrieval/datasets.py index fb24ab4ea..8b468d20f 100644 --- a/siibra/retrieval/datasets.py +++ b/siibra/retrieval/datasets.py @@ -12,7 +12,7 @@ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. - +"""Metadata connection to EBRAINS datasets.""" from .requests import MultiSourcedRequest, GitlabProxy, GitlabProxyEnum diff --git a/siibra/retrieval/exceptions/__init__.py b/siibra/retrieval/exceptions/__init__.py index 3d546e0ab..e77664745 100644 --- a/siibra/retrieval/exceptions/__init__.py +++ b/siibra/retrieval/exceptions/__init__.py @@ -1,3 +1,19 @@ +# Copyright 2018-2021 +# Institute of Neuroscience and Medicine (INM-1), Forschungszentrum Jülich GmbH + +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at + +# http://www.apache.org/licenses/LICENSE-2.0 + +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +"""Exceptions concerning file retrieval processes.""" + class NoSiibraConfigMirrorsAvailableException(Exception): pass diff --git a/siibra/retrieval/repositories.py b/siibra/retrieval/repositories.py index fa60a4d45..42ee69cda 100644 --- a/siibra/retrieval/repositories.py +++ b/siibra/retrieval/repositories.py @@ -12,6 +12,7 @@ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. +"""Connect to repositories to browse and pull files within.""" from .requests import ( HttpRequest, diff --git a/siibra/retrieval/requests.py b/siibra/retrieval/requests.py index b219bbe86..9e815f653 100644 --- a/siibra/retrieval/requests.py +++ b/siibra/retrieval/requests.py @@ -12,6 +12,7 @@ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. +"""Request files with decoders, lazy loading, and caching.""" from .cache import CACHE from .exceptions import EbrainsAuthenticationError diff --git a/siibra/vocabularies/__init__.py b/siibra/vocabularies/__init__.py index b5622aaff..d12c430fe 100644 --- a/siibra/vocabularies/__init__.py +++ b/siibra/vocabularies/__init__.py @@ -12,7 +12,7 @@ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. - +"""Abbreviations and aliases.""" from ..commons import InstanceTable diff --git a/siibra/volumes/gifti.py b/siibra/volumes/gifti.py index bd7cb5380..8599f6d63 100644 --- a/siibra/volumes/gifti.py +++ b/siibra/volumes/gifti.py @@ -12,6 +12,7 @@ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. +"""Handles reading and preparing gii files.""" from . import volume diff --git a/siibra/volumes/neuroglancer.py b/siibra/volumes/neuroglancer.py index d599e318b..1a710d993 100644 --- a/siibra/volumes/neuroglancer.py +++ b/siibra/volumes/neuroglancer.py @@ -12,6 +12,7 @@ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. +"""Handles reading and preparing neuroglancer files.""" from . import volume diff --git a/siibra/volumes/nifti.py b/siibra/volumes/nifti.py index 8617f2dd8..37d18eb8a 100644 --- a/siibra/volumes/nifti.py +++ b/siibra/volumes/nifti.py @@ -12,6 +12,7 @@ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. +"""Handles reading and preparing nifti files.""" from . import volume