Prefix files with underscore to hide them from sphinx-autodoc.

This avoids unnecessary submodules in the auto-generated documentation; the
organization of functions into files is an implementation detail.

We also update the links to various scranpy functions.

Author: LTLA

.github/workflows/build-docs.yml

@@ -24,7 +24,7 @@ jobs:
 
       - name: Build docs
         run: |
-          touch src/singler/lib_singler.py
+          touch src/singler/_lib_singler.py
           pip install tox
           tox -e docs
 

.gitignore

@@ -54,3 +54,4 @@ MANIFEST
 .python-version
 
 _cache
+src/singler/_lib_singler.py

docs/conf.py

@@ -302,16 +302,14 @@
 intersphinx_mapping = {
     "sphinx": ("https://www.sphinx-doc.org/en/master", None),
     "python": ("https://docs.python.org/" + python_version, None),
-    "matplotlib": ("https://matplotlib.org", None),
     "numpy": ("https://numpy.org/doc/stable", None),
-    "sklearn": ("https://scikit-learn.org/stable", None),
-    "pandas": ("https://pandas.pydata.org/pandas-docs/stable", None),
     "scipy": ("https://docs.scipy.org/doc/scipy/reference", None),
     "setuptools": ("https://setuptools.pypa.io/en/stable/", None),
     "pyscaffold": ("https://pyscaffold.org/en/stable", None),
     "biocframe": ("https://biocpy.github.io/BiocFrame", None),
     "summarizedexperiment": ("https://biocpy.github.io/SummarizedExperiment", None),
     "singlecellexperiment": ("https://biocpy.github.io/SingleCellExperiment", None),
+    "scranpy": ("https://libscran.github.io/scranpy", None),
 }
 
 print(f"loading configurations for {project} {version} ...", file=sys.stderr)

lib/CMakeLists.txt

@@ -27,6 +27,6 @@ set_property(TARGET singler PROPERTY CXX_STANDARD 17)
 target_link_libraries(singler PRIVATE pybind11::pybind11)
 
 set_target_properties(singler PROPERTIES
-    OUTPUT_NAME lib_singler
+    OUTPUT_NAME _lib_singler
     PREFIX ""
 )

lib/src/init.cpp

@@ -7,7 +7,7 @@ void init_classify_single(pybind11::module&);
 void init_train_integrated(pybind11::module&);
 void init_classify_integrated(pybind11::module&);
 
-PYBIND11_MODULE(lib_singler, m) {
+PYBIND11_MODULE(_lib_singler, m) {
     init_find_classic_markers(m);
     init_train_single(m);
     init_classify_single(m);

src/singler/__init__.py

@@ -8,19 +8,26 @@
 
 try:
     # Change here if project is renamed and does not equal the package name
-    dist_name = __name__
-    __version__ = version(dist_name)
+    _dist_name = __name__
+    __version__ = version(_dist_name)
 except PackageNotFoundError:  # pragma: no cover
     __version__ = "unknown"
 finally:
     del version, PackageNotFoundError
 
 
-from .get_classic_markers import get_classic_markers, number_of_classic_markers
-from .train_single import train_single, TrainedSingleReference
-from .classify_single import classify_single
-from .annotate_single import annotate_single
-from .train_integrated import train_integrated, TrainedIntegratedReferences
-from .classify_integrated import classify_integrated
-from .annotate_integrated import annotate_integrated
-from .aggregate_reference import aggregate_reference
+from ._get_classic_markers import get_classic_markers, number_of_classic_markers
+from ._train_single import train_single, TrainedSingleReference
+from ._classify_single import classify_single
+from ._annotate_single import annotate_single
+from ._train_integrated import train_integrated, TrainedIntegratedReferences
+from ._classify_integrated import classify_integrated
+from ._annotate_integrated import annotate_integrated
+from ._aggregate_reference import aggregate_reference
+
+
+__all__ = []
+for _name in dir():
+    if _name.startswith("_") or _name == "sys":
+        continue
+    __all__.append(_name)

src/singler/aggregate_reference.py src/singler/_aggregate_reference.pysrc/singler/aggregate_reference.py renamed to src/singler/_aggregate_reference.py

@@ -22,7 +22,7 @@ def aggregate_reference(
     num_threads: int = 1
 ) -> summarizedexperiment.SummarizedExperiment:
     """Aggregate reference samples for a given label by using vector quantization to average their count profiles.
-    The idea is to reduce the size of single-cell reference datasets so as to reduce the computation time of :py:func:`~singler.train_single.train_single`.
+    The idea is to reduce the size of single-cell reference datasets so as to reduce the computation time of :py:func:`~singler.train_single`.
     We perform k-means clustering for all cells in each label and aggregate all cells within each k-means cluster.
     (More specifically, the clustering is done on the principal components generated from the highly variable genes to better capture the structure within each label.)
     This yields one or more profiles per label, reducing the number of separate observations while preserving some level of intra-label heterogeneity.
@@ -39,7 +39,7 @@ def aggregate_reference(
             Sequence of identifiers for each feature, i.e., row in ``ref_data``.
 
         num_centers:
-            Maximum number of aggregated profiles to produce for each label with :py:func:`~scranpy.cluster_kmeans.cluster_kmeans`.
+            Maximum number of aggregated profiles to produce for each label with :py:func:`~scranpy.cluster_kmeans`.
             If ``None``, a suitable number of profiles is automatically chosen. 
 
         power:
@@ -48,10 +48,10 @@ def aggregate_reference(
             Ignored if ``num_centers`` is not ``None``.
 
         num_top:
-            Number of highly variable genes to use for PCA prior to clustering, see :py:func:`~scranpy.choose_highly_variable_genes.choose_highly_variable_genes`.
+            Number of highly variable genes to use for PCA prior to clustering, see :py:func:`~scranpy.choose_highly_variable_genes`.
 
         rank:
-            Number of principal components to use during clustering, see :py:func:`~scranpy.run_pca.run_pca`.
+            Number of principal components to use during clustering, see :py:func:`~scranpy.run_pca`.
 
         assay_type:
             Integer or string specifying the assay of ``ref_data`` containing the relevant expression matrix,

src/singler/annotate_integrated.py src/singler/_annotate_integrated.pysrc/singler/annotate_integrated.py renamed to src/singler/_annotate_integrated.py

@@ -4,10 +4,10 @@
 import warnings
 
 from ._utils import _clean_matrix, _restrict_features
-from .train_single import train_single
-from .train_integrated import train_integrated
-from .classify_single import classify_single
-from .classify_integrated import classify_integrated
+from ._train_single import train_single
+from ._train_integrated import train_integrated
+from ._classify_single import classify_single
+from ._classify_integrated import classify_integrated
 
 
 def annotate_integrated(
@@ -46,7 +46,7 @@ def annotate_integrated(
             - A matrix-like object representing the reference dataset, where rows
               are features and columns are samples. Entries should be expression values,
               usually log-transformed (see comments for the ``ref_data`` argument in
-              :py:func:`~singler.train_single.train_single`).
+              :py:func:`~singler.train_single`).
             - A ``SummarizedExperiment`` object containing such a matrix in its assays.
 
         ref_labels:
@@ -86,30 +86,30 @@ def annotate_integrated(
 
         train_single_args:
             Further arguments to pass to
-            :py:func:`~singler.train_single.train_single`.
+            :py:func:`~singler.train_single`.
 
         classify_single_args:
             Further arguments to pass to
-            :py:func:`~singler.classify_single.classify_single`.
+            :py:func:`~singler.classify_single`.
 
         train_integrated_args:
             Further arguments to pass to
-            :py:func:`~singler.train_integrated.train_integrated`.
+            :py:func:`~singler.train_integrated`.
 
         classify_integrated_args:
             Further arguments to pass to
-            :py:func:`~singler.classify_integrated.classify_integrated`.
+            :py:func:`~singler.classify_integrated`.
 
         num_threads:
             Number of threads to use for the various steps.
 
     Returns:
         Tuple where the first element contains per-reference results (i.e. a
         list of BiocFrame outputs, roughly equivalent to running
-        :py:func:`~singler.annotate_single.annotate_single` on each reference)
+        :py:func:`~singler.annotate_single` on each reference)
         and the second element contains integrated results across references
         (i.e., a BiocFrame from
-        :py:func:`~singler.classify_integrated.classify_integrated`).
+        :py:func:`~singler.classify_integrated`).
     """
     nrefs = len(ref_data)
     if nrefs != len(ref_labels):

src/singler/annotate_single.py src/singler/_annotate_single.pysrc/singler/annotate_single.py renamed to src/singler/_annotate_single.py

@@ -4,8 +4,8 @@
 import biocframe
 import summarizedexperiment
 
-from .train_single import train_single 
-from .classify_single import classify_single
+from ._train_single import train_single 
+from ._classify_single import classify_single
 from ._utils import _clean_matrix, _restrict_features
 
 
@@ -41,7 +41,7 @@ def annotate_single(
             A matrix-like object representing the reference dataset, where rows
             are features and columns are samples. Entries should be expression values,
             usually log-transformed (see comments for the ``ref`` argument in
-            :py:func:`~singler.train_single.train_single`).
+            :py:func:`~singler.train_single`).
 
             Alternatively, a
             :py:class:`~summarizedexperiment.SummarizedExperiment.SummarizedExperiment`
@@ -78,18 +78,18 @@ def annotate_single(
 
         train_args:
             Further arguments to pass to
-            :py:func:`~singler.train_single.train_single`.
+            :py:func:`~singler.train_single`.
 
         classify_args:
             Further arguments to pass to
-            :py:func:`~singler.classify_single.classify_single`.
+            :py:func:`~singler.classify_single`.
 
         num_threads:
             Number of threads to use for the various steps.
 
     Returns:
         A :py:class:`~biocframe.BiocFrame.BiocFrame` of labelling results, see
-        :py:func:`~singler.classify_single.classify_single` for details.
+        :py:func:`~singler.classify_single` for details.
     """
     if isinstance(ref_labels, str):
         warnings.warn(

src/singler/classify_integrated.py src/singler/_classify_integrated.pysrc/singler/classify_integrated.py renamed to src/singler/_classify_integrated.py

@@ -6,8 +6,8 @@
 import summarizedexperiment
 import numpy
 
-from . import lib_singler as lib
-from .train_integrated import TrainedIntegratedReferences
+from . import _lib_singler as lib
+from ._train_integrated import TrainedIntegratedReferences
 
 
 def classify_integrated(
@@ -35,13 +35,13 @@ def classify_integrated(
 
         results:
             List of classification results generated by running
-            :py:func:`~singler.classify_single.classify_single` on
+            :py:func:`~singler.classify_single` on
             ``test_data`` with each reference. References should be in the
             same order as that used to construct ``integrated_prebuilt``.
 
         integrated_prebuilt:
             Integrated reference object, constructed with
-            :py:func:`~singler.train_integrated.train_integrated`.
+            :py:func:`~singler.train_integrated`.
 
         assay_type:
             Assay containing the expression matrix, if ``test_data`` is a