add docstrings and make stuff private

bioimageio/core/__init__.py

@@ -15,8 +15,9 @@
 from bioimageio.spec import save_bioimageio_yaml_only as save_bioimageio_yaml_only
 from bioimageio.spec import validate_format as validate_format
 
-from .prediction_pipeline import create_prediction_pipeline as create_prediction_pipeline
-from .resource_tests import load_description_and_test as load_description_and_test
-from .resource_tests import test_description as test_description
+from ._prediction_pipeline import create_prediction_pipeline as create_prediction_pipeline
+from ._resource_tests import load_description_and_test as load_description_and_test
+from ._resource_tests import test_description as test_description
+from ._resource_tests import test_model as test_model
 
 test_resource = test_description

bioimageio/core/resource_tests.py → bioimageio/core/_resource_tests.py

@@ -6,7 +6,7 @@
 import xarray as xr
 
 from bioimageio.core import __version__ as bioimageio_core_version
-from bioimageio.core.prediction_pipeline import create_prediction_pipeline
+from bioimageio.core._prediction_pipeline import create_prediction_pipeline
 from bioimageio.spec import InvalidDescr, ResourceDescr, build_description, dump_description, load_description
 from bioimageio.spec._internal.base_nodes import ResourceDescrBase
 from bioimageio.spec._internal.io_utils import load_array
@@ -28,6 +28,63 @@ def test_model(
     )
 
 
+def test_description(
+    source: Union[ResourceDescr, FileSource, BioimageioYamlContent],
+    *,
+    format_version: Union[Literal["discover", "latest"], str] = "discover",
+    weight_format: Optional[WeightsFormat] = None,
+    devices: Optional[List[str]] = None,
+    decimal: int = 4,
+    expected_type: Optional[str] = None,
+) -> ValidationSummary:
+    """Test RDF dynamically, e.g. model inference of test inputs"""
+    rd = load_description_and_test(
+        source,
+        format_version=format_version,
+        weight_format=weight_format,
+        devices=devices,
+        decimal=decimal,
+        expected_type=expected_type,
+    )
+    return rd.validation_summary
+
+
+def load_description_and_test(
+    source: Union[ResourceDescr, FileSource, BioimageioYamlContent],
+    *,
+    format_version: Union[Literal["discover", "latest"], str] = "discover",
+    weight_format: Optional[WeightsFormat] = None,
+    devices: Optional[List[str]] = None,
+    decimal: int = 4,
+    expected_type: Optional[str] = None,
+) -> Union[ResourceDescr, InvalidDescr]:
+    """Test RDF dynamically, e.g. model inference of test inputs"""
+    if (
+        isinstance(source, ResourceDescrBase)
+        and format_version != "discover"
+        and source.format_version != format_version
+    ):
+        warnings.warn(f"deserializing source to ensure we validate and test using format {format_version}")
+        source = dump_description(source)
+
+    if isinstance(source, ResourceDescrBase):
+        rd = source
+    elif isinstance(source, dict):
+        rd = build_description(source, format_version=format_version)
+    else:
+        rd = load_description(source, format_version=format_version)
+
+    rd.validation_summary.env.append(InstalledPackage(name="bioimageio.core", version=bioimageio_core_version))
+
+    if expected_type is not None:
+        _test_expected_resource_type(rd, expected_type)
+
+    if isinstance(rd, (v0_4.ModelDescr, v0_5.ModelDescr)):
+        _test_model_inference(rd, weight_format, devices, decimal)
+
+    return rd
+
+
 def _test_model_inference(
     model: Union[v0_4.ModelDescr, v0_5.ModelDescr],
     weight_format: Optional[WeightsFormat],
@@ -104,63 +161,6 @@ def _test_expected_resource_type(rd: Union[InvalidDescr, ResourceDescr], expecte
     )
 
 
-def test_description(
-    source: Union[ResourceDescr, FileSource, BioimageioYamlContent],
-    *,
-    format_version: Union[Literal["discover", "latest"], str] = "discover",
-    weight_format: Optional[WeightsFormat] = None,
-    devices: Optional[List[str]] = None,
-    decimal: int = 4,
-    expected_type: Optional[str] = None,
-) -> ValidationSummary:
-    """Test RDF dynamically, e.g. model inference of test inputs"""
-    rd = load_description_and_test(
-        source,
-        format_version=format_version,
-        weight_format=weight_format,
-        devices=devices,
-        decimal=decimal,
-        expected_type=expected_type,
-    )
-    return rd.validation_summary
-
-
-def load_description_and_test(
-    source: Union[ResourceDescr, FileSource, BioimageioYamlContent],
-    *,
-    format_version: Union[Literal["discover", "latest"], str] = "discover",
-    weight_format: Optional[WeightsFormat] = None,
-    devices: Optional[List[str]] = None,
-    decimal: int = 4,
-    expected_type: Optional[str] = None,
-) -> Union[ResourceDescr, InvalidDescr]:
-    """Test RDF dynamically, e.g. model inference of test inputs"""
-    if (
-        isinstance(source, ResourceDescrBase)
-        and format_version != "discover"
-        and source.format_version != format_version
-    ):
-        warnings.warn(f"deserializing source to ensure we validate and test using format {format_version}")
-        source = dump_description(source)
-
-    if isinstance(source, ResourceDescrBase):
-        rd = source
-    elif isinstance(source, dict):
-        rd = build_description(source, format_version=format_version)
-    else:
-        rd = load_description(source, format_version=format_version)
-
-    rd.validation_summary.env.append(InstalledPackage(name="bioimageio.core", version=bioimageio_core_version))
-
-    if expected_type is not None:
-        _test_expected_resource_type(rd, expected_type)
-
-    if isinstance(rd, (v0_4.ModelDescr, v0_5.ModelDescr)):
-        _test_model_inference(rd, weight_format, devices, decimal)
-
-    return rd
-
-
 # def debug_model(
 #     model_rdf: Union[RawResourceDescr, ResourceDescr, URI, Path, str],
 #     *,

bioimageio/core/common.py

@@ -1,9 +1,9 @@
 from dataclasses import dataclass, field
-from typing import TYPE_CHECKING, Dict, Union
+from typing import TYPE_CHECKING, Dict
 
 import xarray as xr
 
-from bioimageio.spec.model import v0_4, v0_5
+from bioimageio.spec.model import v0_5
 
 if TYPE_CHECKING:
     from bioimageio.core.stat_measures import Measure, MeasureValue
@@ -19,9 +19,10 @@
 
 @dataclass
 class Sample:
-    data: Data = field(default_factory=dict)
-    stat: Stat = field(default_factory=dict)
+    """A (dataset) sample"""
 
+    data: Data = field(default_factory=dict)
+    """the samples tensors"""
 
-ProcessingDescrBase = Union[v0_4.ProcessingDescrBase, v0_5.ProcessingDescrBase]
-ProcessingKwargs = Union[v0_4.ProcessingKwargs, v0_5.ProcessingKwargs]
+    stat: Stat = field(default_factory=dict)
+    """sample and dataset statistics"""

bioimageio/core/prediction.py

@@ -1,3 +1,5 @@
+"""coming soon"""
+
 # TODO: update
 # import collections
 # import os

bioimageio/core/proc_ops.py

@@ -19,14 +19,14 @@
 from numpy.typing import DTypeLike
 from typing_extensions import Self, assert_never
 
+from bioimageio.core._op_base import Operator
 from bioimageio.core.common import (
     AxisId,
     Sample,
     Stat,
     Tensor,
     TensorId,
 )
-from bioimageio.core.op_base import Operator
 from bioimageio.core.stat_calculators import StatsCalculator
 from bioimageio.core.stat_measures import (
     DatasetMean,

bioimageio/core/proc_setup.py

@@ -40,6 +40,9 @@ def setup_pre_and_postprocessing(
     keep_updating_initial_dataset_stats: bool = False,
     fixed_dataset_stats: Mapping[DatasetMeasure, MeasureValue] = MappingProxyType({}),
 ) -> PreAndPostprocessing:
+    """
+    Get pre- and postprocessing operators for a `model` description.
+    userd in `bioimageio.core.create_prediction_pipeline"""
     prep, post, prep_meas, post_meas = _prepare_setup_pre_and_postprocessing(model)
 
     missing_dataset_stats = {m for m in prep_meas | post_meas if m not in fixed_dataset_stats}

bioimageio/core/stat_calculators.py

@@ -65,6 +65,8 @@ def quantile(self, q: Any) -> Any:
 
 
 class MeanCalculator:
+    """to calculate sample and dataset mean"""
+
     def __init__(self, tensor_id: TensorId, axes: Optional[Sequence[AxisId]]):
         super().__init__()
         self._n: int = 0
@@ -115,6 +117,8 @@ def finalize(self) -> Dict[DatasetMean, MeasureValue]:
 
 
 class MeanVarStdCalculator:
+    """to calculate sample and dataset mean, variance or standard deviation"""
+
     def __init__(self, tensor_id: TensorId, axes: Optional[Sequence[AxisId]]):
         super().__init__()
         self._axes = None if axes is None else tuple(axes)
@@ -181,6 +185,8 @@ def finalize(self) -> Dict[Union[DatasetMean, DatasetVar, DatasetStd], MeasureVa
 
 
 class SamplePercentilesCalculator:
+    """to calculate sample percentiles"""
+
     def __init__(self, tensor_id: TensorId, axes: Optional[Sequence[AxisId]], ns: Collection[float]):
         super().__init__()
         assert all(0 <= n <= 100 for n in ns)
@@ -196,6 +202,9 @@ def compute(self, sample: Sample) -> Dict[SamplePercentile, MeasureValue]:
 
 
 class MeanPercentilesCalculator:
+    """to calculate dataset percentiles heuristically by averaging across samples
+    **note**: the returned dataset percentiles are an estiamte and **not mathematically correct**"""
+
     def __init__(self, tensor_id: TensorId, axes: Optional[Sequence[AxisId]], ns: Collection[float]):
         super().__init__()
         assert all(0 <= n <= 100 for n in ns)
@@ -234,6 +243,8 @@ def finalize(self) -> Dict[DatasetPercentile, MeasureValue]:
 
 
 class CrickPercentilesCalculator:
+    """to calculate dataset percentiles with the experimental [crick libray](https://github.com/dask/crick)"""
+
     def __init__(self, tensor_id: TensorId, axes: Optional[Sequence[AxisId]], ns: Collection[float]):
         warnings.warn("Computing dataset percentiles with experimental 'crick' library.")
         super().__init__()
@@ -297,7 +308,7 @@ def finalize(self) -> Dict[DatasetPercentile, MeasureValue]:
     DatasetPercentilesCalculator = CrickPercentilesCalculator
 
 
-class NaivSampleMeasureCalculator:
+class NaiveSampleMeasureCalculator:
     """wrapper for measures to match interface of other sample measure calculators"""
 
     def __init__(self, tensor_id: TensorId, measure: SampleMeasure):
@@ -310,7 +321,7 @@ def compute(self, sample: Sample) -> Dict[SampleMeasure, MeasureValue]:
 
 
 SampleMeasureCalculator = Union[
-    MeanCalculator, MeanVarStdCalculator, SamplePercentilesCalculator, NaivSampleMeasureCalculator
+    MeanCalculator, MeanVarStdCalculator, SamplePercentilesCalculator, NaiveSampleMeasureCalculator
 ]
 DatasetMeasureCalculator = Union[MeanCalculator, MeanVarStdCalculator, DatasetPercentilesCalculator]