Merge pull request #167 from JonathanShor/doc_refresh

Update docs

Author: JonathanShor

docs/api.md

@@ -0,0 +1,24 @@
+# API
+
+## Plot
+
+```{eval-rst}
+.. currentmodule:: doubletdetection
+
+.. autosummary::
+    :toctree: generated
+
+    BoostClassifier
+```
+
+## Plot
+
+```{eval-rst}
+.. currentmodule:: doubletdetection
+
+.. autosummary::
+    :toctree: generated
+
+    plot.convergence
+    plot.threshold
+```

docs/api.rst

@@ -23,68 +23,108 @@
 copyright = "2022, Adam Gayoso and Jonathan Shor"
 author = "Adam Gayoso and Jonathan Shor"
 
+repository_url = f"https://github.com/JonathanShor/{project}"
+
+
+
+templates_path = ["_templates"]
+html_context = {
+    "display_github": True,  # Integrate GitHub
+    "github_user": "JonathanShor",  # Username
+    "github_repo": "DoubletDetection",  # Repo name
+    "github_version": "main",  # Version
+    "conf_py_path": "/docs/",  # Path in the checkout to the docs root
+}
 
 # -- General configuration ---------------------------------------------------
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 
-needs_sphinx = "4.3"  # Nicer param docs
-
 extensions = [
-    "sphinx.ext.autodoc",
+    "myst_nb",
     "sphinx.ext.viewcode",
-    "myst_parser",
-    "nbsphinx",
-    "nbsphinx_link",
-    "sphinx.ext.mathjax",
-    "sphinx.ext.napoleon",
-    "sphinx_autodoc_typehints",  # needs to be after napoleon
+    "sphinx.ext.autodoc",
+    "sphinx_copybutton",
     "sphinx.ext.intersphinx",
     "sphinx.ext.autosummary",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.extlinks",
+    "sphinx_autodoc_typehints",
+    "sphinx.ext.mathjax",
+    "IPython.sphinxext.ipython_console_highlighting",
+    "sphinxext.opengraph",
 ]
 
-# nbsphinx specific settings
-nbsphinx_execute = "never"
-
-# Add any paths that contain templates here, relative to this directory.
-templates_path = ["_templates"]
+autosummary_generate = True
+autodoc_member_order = "groupwise"
+default_role = "literal"
+bibtex_reference_style = "author_year"
+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
+myst_heading_anchors = 6  # create anchors for h1-h6
+myst_enable_extensions = [
+    "amsmath",
+    "colon_fence",
+    "deflist",
+    "dollarmath",
+    "html_image",
+    "html_admonition",
+]
+myst_url_schemes = ("http", "https", "mailto")
+nb_output_stderr = "remove"
+nb_execution_mode = "off"
+nb_merge_streams = True
+typehints_defaults = "braces"
+
+source_suffix = {
+    ".rst": "restructuredtext",
+    ".ipynb": "myst-nb",
+    ".myst": "myst-nb",
+}
 
-source_suffix = ".rst"
+intersphinx_mapping = {
+    "anndata": ("https://anndata.readthedocs.io/en/stable/", None),
+    "ipython": ("https://ipython.readthedocs.io/en/stable/", None),
+    "matplotlib": ("https://matplotlib.org/", None),
+    "numpy": ("https://numpy.org/doc/stable/", None),
+    "pandas": ("https://pandas.pydata.org/docs/", None),
+    "python": ("https://docs.python.org/3", None),
+    "scipy": ("https://docs.scipy.org/doc/scipy/reference/", None),
+    "sklearn": ("https://scikit-learn.org/stable/", None),
+    "scanpy": ("https://scanpy.readthedocs.io/en/stable/", None),
+}
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "**.ipynb_checkpoints"]
 
-# Generate the API documentation when building
-autosummary_generate = True
-autodoc_member_order = "bysource"
-napoleon_google_docstring = True
-napoleon_include_init_with_doc = False
-napoleon_use_rtype = True  # having a separate entry generally helps readability
-napoleon_use_param = True
-napoleon_custom_sections = [("Params", "Parameters")]
+# extlinks config
+extlinks = {
+    "issue": (f"{repository_url}/issues/%s", "#%s"),
+    "pr": (f"{repository_url}/pull/%s", "#%s"),
+    "ghuser": ("https://github.com/%s", "@%s"),
+}
+
+
 
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = "furo"
+html_theme = "sphinx_book_theme"
 
 html_title = "DoubletDetection"
 
 html_theme_options = {
-    "sidebar_hide_name": False,
-    "light_css_variables": {
-        "color-brand-primary": "#003262",
-        "color-brand-content": "#003262",
-        "admonition-font-size": "var(--font-size-normal)",
-        "admonition-title-font-size": "var(--font-size-normal)",
-        "code-font-size": "var(--font-size--small)",
-    },
+    "repository_url": "https://github.com/JonathanShor/DoubletDetection",
+    "use_repository_button": True,
 }
 
 # Add any paths that contain custom static files (such as style sheets) here,

docs/conf.py

@@ -0,0 +1,12 @@
+```{include} ../README.md
+
+```
+
+```{toctree}
+:hidden: true
+:maxdepth: 1
+
+api
+plot
+tutorial
+```

docs/index.md

@@ -23,64 +23,51 @@ class BoostClassifier:
     """Classifier for doublets in single-cell RNA-seq data.
 
     Parameters:
-        boost_rate (float, optional): Proportion of cell population size to
-            produce as synthetic doublets.
-        n_components (int, optional): Number of principal components used for
-            clustering.
-        n_top_var_genes (int, optional): Number of highest variance genes to
-            use; other genes discarded. Will use all genes when zero.
-        replace (bool, optional): If False, a cell will be selected as a
-            synthetic doublet's parent no more than once.
-        self.clustering_algorithm (str, optional): One of `["louvain", "leiden",
-        "phenograph"]`. `"louvain"` and `leiden` refer to the scanpy implementations.
-        clustering_kwargs (dict, optional): Keyword args to pass directly
-            to clusering algorithm. Note that we change the PhenoGraph 'prune' default to
-            True. We also set `directed=False` and `resolution=4` for Louvain
-            and Leiden clustering. You must specifically include these params here
-            to change them. `random_state` and `key_added` should not be overriden
-            when clustering algorithm is Louvain or Leiden.
-        n_iters (int, optional): Number of fit operations from which to collect
-            p-values. Defualt value is 25.
-        normalizer ((sp_sparse) -> ndarray): Method to normalize raw_counts.
-            Defaults to normalize_counts, included in this package. Note: To use
-            normalize_counts with its pseudocount parameter changed from the
-            default pseudocount value to some positive float `new_var`, use:
-            normalizer=lambda counts: doubletdetection.normalize_counts(counts,
-            pseudocount=new_var)
-        pseudocount (int, optional): Pseudocount used in normalize_counts.
-            If `1` is used, and `standard_scaling=False`, the classifier is
-            much more memory efficient; however, this may result in fewer doublets
-            detected.
-        random_state (int, optional): If provided, passed to PCA and used to
-            seedrandom seed numpy's RNG. NOTE: PhenoGraph does not currently
-            admit a random seed, and so this will not guarantee identical
-            results across runs.
-        verbose (bool, optional): Set to False to silence all normal operation
-            informational messages. Defaults to True.
-        standard_scaling (bool, optional): Set to True to enable standard scaling
-            of normalized count matrix prior to PCA. Recommended when not using
-            Phenograph. Defaults to False.
-        n_jobs (int, optional): Number of jobs to use. Speeds up neighbor computation.
+        boost_rate: Proportion of cell population size to produce as synthetic doublets.
+        n_components: Number of principal components used for clustering.
+        n_top_var_genes: Number of highest variance genes to use. Other genes are
+            discarded. Will use all genes when zero.
+        replace: If False, a cell will be selected as a synthetic doublet's parent
+            no more than once.
+        clustering_algorithm: One of "louvain", "leiden", or "phenograph". "louvain"
+            and "leiden" refer to the scanpy implementations.
+        clustering_kwargs: Keyword args to pass directly to clustering algorithm.
+            Note that PhenoGraph 'prune' default is changed to True. For Louvain and
+            Leiden clustering, we set `directed=False` and `resolution=4`. Include
+            these params explicitly to change them. Do not override `random_state`
+            and `key_added` for Louvain/Leiden.
+        n_iters: Number of fit operations from which to collect p-values. Default is 25.
+        normalizer: Method to normalize raw_counts. Defaults to normalize_counts from
+            this package. To use normalize_counts with a different pseudocount value,
+            use: `lambda counts: doubletdetection.normalize_counts(counts,
+            pseudocount=new_value)`
+        pseudocount: Pseudocount used in normalize_counts. Using 1 with
+            standard_scaling=False makes the classifier more memory efficient but may
+            detect fewer doublets.
+        random_state: Passed to PCA and doublet parent creation. Note: PhenoGraph does not
+            support random seeds, so identical results aren't guaranteed across runs.
+        verbose: Set to False to silence informational messages. Defaults to True.
+        standard_scaling: Enable standard scaling of normalized count matrix prior to
+            PCA. Recommended when not using Phenograph. Defaults to False.
+        n_jobs: Number of jobs to use. Speeds up neighbor computation.
 
     Attributes:
-        all_log_p_values_ (ndarray): Hypergeometric test natural log p-value per
-            cell for cluster enrichment of synthetic doublets. Use for tresholding.
+        all_log_p_values_: Hypergeometric test natural log p-value per cell for
+            cluster enrichment of synthetic doublets. Use for thresholding.
             Shape (n_iters, num_cells).
-        all_scores_ (ndarray): The fraction of a cell's cluster that is
-            synthetic doublets. Shape (n_iters, num_cells).
-        communities_ (ndarray): Cluster ID for corresponding cell. Shape
-            (n_iters, num_cells).
-        labels_ (ndarray, ndims=1): 0 for singlet, 1 for detected doublet.
-        parents_ (list of sequences of int): Parent cells' indexes for each
-            synthetic doublet. A list wrapping the results from each run.
-        suggested_score_cutoff_ (float): Cutoff used to classify cells when
-            n_iters == 1 (scores >= cutoff). Not produced when n_iters > 1.
-        synth_communities_ (sequence of ints): Cluster ID for corresponding
-            synthetic doublet. Shape (n_iters, num_cells * boost_rate).
-        top_var_genes_ (ndarray): Indices of the n_top_var_genes used. Not
-            generated if n_top_var_genes <= 0.
-        voting_average_ (ndarray): Fraction of iterations each cell is called a
-            doublet.
+        all_scores_: The fraction of a cell's cluster that is synthetic doublets.
+            Shape (n_iters, num_cells).
+        communities_: Cluster ID for corresponding cell. Shape (n_iters, num_cells).
+        labels_: 0 for singlet, 1 for detected doublet.
+        parents_: Parent cells' indexes for each synthetic doublet. A list wrapping
+            the results from each run.
+        suggested_score_cutoff_: Cutoff used to classify cells when n_iters == 1
+            (scores >= cutoff). Not produced when n_iters > 1.
+        synth_communities_: Cluster ID for corresponding synthetic doublet.
+            Shape (n_iters, num_cells * boost_rate).
+        top_var_genes_: Indices of the n_top_var_genes used. Not generated if
+            n_top_var_genes <= 0.
+        voting_average_: Fraction of iterations each cell is called a doublet.
     """
 
     def __init__(
@@ -148,7 +135,7 @@ def fit(self, raw_counts: NDArray | sp_sparse.csr_matrix) -> "BoostClassifier":
         """Fits the classifier on raw_counts.
 
         Args:
-            raw_counts (array-like): Count matrix, oriented cells by genes.
+            raw_counts: Count matrix, oriented cells by genes.
 
         Sets:
             all_scores_, all_log_p_values_, communities_,
@@ -229,9 +216,9 @@ def predict(self, p_thresh: float = 1e-7, voter_thresh: float = 0.9) -> NDArray:
         """Produce doublet calls from fitted classifier
 
         Args:
-            p_thresh (float, optional): hypergeometric test p-value threshold
+            p_thresh: hypergeometric test p-value threshold
                 that determines per iteration doublet calls
-            voter_thresh (float, optional): fraction of iterations a cell must
+            voter_thresh: fraction of iterations a cell must
                 be called a doublet
 
         Sets:

docs/index.rst

@@ -48,12 +48,16 @@ dev = [
     "leidenalg",
 ]
 docs = [
-    "sphinx>=4.1,<4.4",
-    "sphinx-autodoc-typehints",
-    "nbsphinx",
-    "nbsphinx-link",
-    "furo",
-    "myst-parser",
+    "sphinx>=4",
+    "sphinx-book-theme>=1.0",
+    "myst-nb",
+    "sphinxcontrib-bibtex>=1.0.0",
+    "scanpydoc[typehints]>=0.7.4",
+    "sphinxext-opengraph",
+    # For notebooks
+    "ipython",
+    "ipykernel",
+    "sphinx-copybutton",
 ]
 
 [tool.black]