diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 50861e1cef..d0277037d9 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -3,19 +3,16 @@ Thanks for opening a PR to scanpy! Please be sure to follow the guidelines in our contribution guide (https://scanpy.scverse.org/page/dev/) to familiarize yourself with our workflow and speed up review. --> -**LLM usage** - - - - -- [ ] LLM or coding agent used: -- [ ] If one was used, I, a human, have reviewed, understood and tested every changed line - + - [ ] Closes # - [ ] [Tests][] included or not required because: - + - [ ] [Release notes][] not necessary because: + +- [ ] LLM or coding agent used: +- [ ] If one was used, I, a human, have reviewed, understood and tested every changed line [tests]: https://scanpy.readthedocs.io/page/dev/testing.html#writing-tests [release notes]: https://scanpy.readthedocs.io/page/dev/documentation.html#adding-to-the-docs diff --git a/.panache.toml b/.panache.toml new file mode 100644 index 0000000000..48027337a1 --- /dev/null +++ b/.panache.toml @@ -0,0 +1,12 @@ +#:schema https://panache.bz/panache.schema.json +flavor = "myst" + +[format] +wrap = "preserve" + +# MyST syntax extensions from `scverse_doc.config.MYST_ENABLE_EXTENSIONS` +[extensions] +myst-colon-fence = true # colon_fence +definition-lists = true # deflist +tex-math-dollars = true # dollarmath, amsmath +raw-html = true # html_image, html_admonition diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 88a72298ae..3cee7bda3c 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -15,6 +15,11 @@ repos: - id: biome-format groups: [format] exclude: ^\.cruft\.json$ # inconsistent indentation with cruft - file never to be modified manually. + - repo: https://github.com/jolars/panache-pre-commit + rev: v3.17.2 + hooks: + - id: panache-format + groups: [format] - repo: https://github.com/tox-dev/pyproject-fmt rev: v2.30.3 hooks: diff --git a/README.md b/README.md index 6748305526..d80c717acc 100644 --- a/README.md +++ b/README.md @@ -34,7 +34,7 @@ If you like scverse® and want to support our mission, please consider making a +> @@ -50,8 +50,6 @@ That is, if something is missing from our public API as documented, for example [leading underscore]: https://peps.python.org/pep-0008/#public-and-internal-interfaces [open an issue]: https://github.com/scverse/scanpy/issues/new/choose - - ## Citation If you use `scanpy` in your work, please cite the `scanpy` publication as follows: @@ -60,7 +58,7 @@ If you use `scanpy` in your work, please cite the `scanpy` publication as follow > > F. Alexander Wolf, Philipp Angerer, Fabian J. Theis > -> _Genome Biology_ 2018 Feb 06. doi: [10.1186/s13059-017-1382-0](https://doi.org/10.1186/s13059-017-1382-0). +> *Genome Biology* 2018 Feb 06. doi: [10.1186/s13059-017-1382-0](https://doi.org/10.1186/s13059-017-1382-0). You can cite the scverse publication as follows: @@ -68,7 +66,6 @@ You can cite the scverse publication as follows: > > Isaac Virshup, Danila Bredikhin, Lukas Heumos, Giovanni Palla, Gregor Sturm, Adam Gayoso, Ilia Kats, Mikaela Koutrouli, Scverse Community, Bonnie Berger, Dana Pe’er, Aviv Regev, Sarah A. Teichmann, Francesca Finotello, F. Alexander Wolf, Nir Yosef, Oliver Stegle & Fabian J. Theis > -> _Nat Biotechnol._ 2023 Apr 10. doi: [10.1038/s41587-023-01733-8](https://doi.org/10.1038/s41587-023-01733-8). - +> *Nat Biotechnol.* 2023 Apr 10. doi: [10.1038/s41587-023-01733-8](https://doi.org/10.1038/s41587-023-01733-8). [contribution guide]: CONTRIBUTING.md diff --git a/biome.jsonc b/biome.jsonc index e99b33d7ec..c9ca97fec0 100644 --- a/biome.jsonc +++ b/biome.jsonc @@ -1,7 +1,7 @@ { "$schema": "https://biomejs.dev/schemas/2.6.3/schema.json", "formatter": { "useEditorconfig": true }, - "markdown": { "parser": { "frontmatter": true } }, + "markdown": { "formatter": { "enabled": false } }, // handled by panache "overrides": [ { "includes": ["./.vscode/*.json", "**/*.jsonc", "**/asv.conf.json"], diff --git a/docs/api/classes.md b/docs/api/classes.md index 89019f572a..6a2384961e 100644 --- a/docs/api/classes.md +++ b/docs/api/classes.md @@ -14,5 +14,4 @@ Represent data as a neighborhood structure, usually a knn graph. :toctree: generated/ Neighbors - ``` diff --git a/docs/api/datasets.md b/docs/api/datasets.md index 673d1d0c2b..fc860ba67a 100644 --- a/docs/api/datasets.md +++ b/docs/api/datasets.md @@ -22,5 +22,4 @@ datasets.pbmc68k_reduced datasets.paul15 datasets.visium_sge - ``` diff --git a/docs/api/get.md b/docs/api/get.md index 48f8b34549..ab05af63e7 100644 --- a/docs/api/get.md +++ b/docs/api/get.md @@ -21,5 +21,4 @@ useful formats. get.pca get.rank_genes_groups_df get.aggregate - ``` diff --git a/docs/api/metrics.md b/docs/api/metrics.md index 0df3d2e51d..c00d489066 100644 --- a/docs/api/metrics.md +++ b/docs/api/metrics.md @@ -19,5 +19,4 @@ Collections of useful measurements for evaluating results. metrics.confusion_matrix metrics.gearys_c metrics.morans_i - ``` diff --git a/docs/api/plotting.md b/docs/api/plotting.md index c138093fa9..85b877b675 100644 --- a/docs/api/plotting.md +++ b/docs/api/plotting.md @@ -37,7 +37,6 @@ Functions with both backends: pl.stacked_violin pl.matrixplot pl.ranking - ``` Helper for computing dot areas, e.g. for {func}`~scanpy.pl.dotplot`: @@ -48,7 +47,6 @@ Helper for computing dot areas, e.g. for {func}`~scanpy.pl.dotplot`: :toctree: generated/ pl.dot_area - ``` Legacy (matplotlib) only: @@ -60,7 +58,6 @@ Legacy (matplotlib) only: pl.clustermap pl.dendrogram - ``` ## Classes @@ -75,7 +72,6 @@ These classes allow fine tuning of visual parameters. pl.DotPlot pl.MatrixPlot pl.StackedViolin - ``` ## Preprocessing @@ -91,7 +87,6 @@ Methods for visualizing quality control and results of preprocessing functions. pl.highest_expr_genes pl.highly_variable_genes pl.scrublet_score_distribution - ``` ## Tools diff --git a/docs/api/preprocessing.md b/docs/api/preprocessing.md index 4715856c89..664647d6f7 100644 --- a/docs/api/preprocessing.md +++ b/docs/api/preprocessing.md @@ -10,7 +10,7 @@ Filtering of highly-variable genes, batch-effect correction, per-cell normalization, preprocessing recipes. -Any transformation of the data matrix that is not a _tool_. Other than _tools_, preprocessing steps usually don't return an easily interpretable annotation, but perform a basic transformation on the data matrix. +Any transformation of the data matrix that is not a *tool*. Other than *tools*, preprocessing steps usually don't return an easily interpretable annotation, but perform a basic transformation on the data matrix. ## Basic Preprocessing @@ -96,7 +96,6 @@ Also see {ref}`data integration tools ` and external {ref}`ext pp.bbknn pp.neighbors - ``` ## Output types diff --git a/docs/api/queries.md b/docs/api/queries.md index ea6d5fa79b..070cdf73d4 100644 --- a/docs/api/queries.md +++ b/docs/api/queries.md @@ -18,5 +18,4 @@ This module provides useful queries for annotation and enrichment. queries.biomart_annotations queries.mitochondrial_genes queries.enrich - ``` diff --git a/docs/api/settings.md b/docs/api/settings.md index ed39d9ccda..12e3b5864a 100644 --- a/docs/api/settings.md +++ b/docs/api/settings.md @@ -63,7 +63,6 @@ you'd usually want to set {attr}`settings.autoshow` to `False`. IO related settings for saving figures, caching files and storing datasets. - ```{eval-rst} .. autosummary:: diff --git a/docs/api/tools.md b/docs/api/tools.md index 245e3e355f..ce21eaf4c0 100644 --- a/docs/api/tools.md +++ b/docs/api/tools.md @@ -8,7 +8,7 @@ .. currentmodule:: scanpy ``` -Any transformation of the data matrix that is not _preprocessing_. In contrast to a _preprocessing_ function, a _tool_ usually adds an easily interpretable annotation to the data matrix, which can then be visualized with a corresponding plotting function. +Any transformation of the data matrix that is not *preprocessing*. In contrast to a *preprocessing* function, a *tool* usually adds an easily interpretable annotation to the data matrix, which can then be visualized with a corresponding plotting function. ## Embeddings diff --git a/docs/dev/documentation.md b/docs/dev/documentation.md index 4b9fc582f3..f80dca4838 100644 --- a/docs/dev/documentation.md +++ b/docs/dev/documentation.md @@ -17,7 +17,7 @@ Next, if problems persist, clear the sphinx cache (`hatch run docs:clean`) and t ## Adding to the docs For any user-visible changes, please make sure a note has been added to the release notes using `hatch run towncrier:create` (see towncrier’s {doc}`towncrier:tutorial`). -When asked for “Issue number (`+` if none)”, enter the _PR number_ instead. +When asked for “Issue number (`+` if none)”, enter the *PR number* instead. Once you've added a new function to the documentation, you'll need to make sure there is a link somewhere in the documentation site pointing to it. This should be added to `docs/api.md` under a relevant heading. @@ -74,8 +74,8 @@ If your parameter only accepts an enumeration of strings, specify them like so: There are three types of return sections – prose, tuple, and a mix of both. 1. Prose is for simple cases. -2. Tuple return sections are formatted like parameters. Other than in numpydoc, each tuple is first characterized by the identifier and _not_ by its type. Provide type annotation in the function header. -3. Mix of prose and tuple is relevant in complicated cases, e.g. when you want to describe that you _added something as annotation to an \`AnnData\` object_. +2. Tuple return sections are formatted like parameters. Other than in numpydoc, each tuple is first characterized by the identifier and *not* by its type. Provide type annotation in the function header. +3. Mix of prose and tuple is relevant in complicated cases, e.g. when you want to describe that you *added something as annotation to an `AnnData` object*. #### Examples diff --git a/docs/dev/getting-set-up.md b/docs/dev/getting-set-up.md index acf5db9ad6..dc3eaf8221 100644 --- a/docs/dev/getting-set-up.md +++ b/docs/dev/getting-set-up.md @@ -7,10 +7,10 @@ This section of the docs covers our practices for working with `git` on our code For a more complete git tutorials we recommend checking out: [Atlassian's git tutorial](https://www.atlassian.com/git/tutorials) -: Beginner friendly introductions to the git command line interface +: Beginner friendly introductions to the git command line interface [Setting up git for GitHub](https://docs.github.com/en/free-pro-team@latest/github/getting-started-with-github/set-up-git) -: Configuring git to work with your GitHub user account +: Configuring git to work with your GitHub user account (forking-and-cloning)= diff --git a/docs/dev/release.md b/docs/dev/release.md index d62f06bf6d..8148c43974 100644 --- a/docs/dev/release.md +++ b/docs/dev/release.md @@ -1,13 +1,13 @@ # Making a release First, check out {doc}`versioning` to see which kind of release you want to make. -That page also explains concepts like _pre-releases_ and applications thereof. +That page also explains concepts like *pre-releases* and applications thereof. ## Preparing the release -1. Switch to the `main` branch for a major/minor release and the respective release series branch for a _patch_ release (e.g. `1.8.x` when releasing version 1.8.4). +1. Switch to the `main` branch for a major/minor release and the respective release series branch for a *patch* release (e.g. `1.8.x` when releasing version 1.8.4). 2. Run `hatch run towncrier:build` to generate a PR that creates a new release notes file. Wait for the PR to be auto-merged. -3. If it is a _patch_ release, merge the backport PR (see {ref}`versioning-tooling`) into the `main` branch. +3. If it is a *patch* release, merge the backport PR (see {ref}`versioning-tooling`) into the `main` branch. ## Actually making the release @@ -17,20 +17,20 @@ That page also explains concepts like _pre-releases_ and applications thereof. 4. Select the dropdown entry {guilabel}`+ Create new tag: 1.. on publish`. 5. In the second dropdown {guilabel}`Target:`, select the base branch i.e. `main` for a minor/major release, and e.g. `1.9.x` for our example patch release `1.9.6`. -6. If the version is a _pre-release_ version, such as `1.7.0rc1` or `1.10.0a1`, tick the {guilabel}`Set as a pre-release` checkbox. +6. If the version is a *pre-release* version, such as `1.7.0rc1` or `1.10.0a1`, tick the {guilabel}`Set as a pre-release` checkbox. [releases]: https://github.com/scverse/scanpy/releases ## After making a release -After _any_ release has been made: +After *any* release has been made: - Create a milestone for the next release (in case you made a bugfix release) or releases (in case of a major/minor release). For bugfix releases, this should have `on-merge: backport to 0..x`, so the [meeseeksdev][] bot will create a backport PR. See {doc}`versioning` for more info. - Clear out and close the milestone you just made a release for. -After a _major_ or _minor_ release has been made: +After a *major* or *minor* release has been made: - Tweet about it! Announce it on Zulip! Announce it on Discourse! Think about making a bot for this! Maybe actually do that? - Create a new release notes file for the next minor release. This should only be added to the dev branch. @@ -57,6 +57,7 @@ $ bsdtar -tf dist/*.whl ``` You can also upload the package to ([tutorial][testpypi tutorial]) + ```console $ twine upload --repository testpypi dist/* ``` diff --git a/docs/dev/versioning.md b/docs/dev/versioning.md index 1980275a1c..385882c782 100644 --- a/docs/dev/versioning.md +++ b/docs/dev/versioning.md @@ -18,10 +18,10 @@ At a `point` release, there should be no changes beyond bug fixes. Valid version numbers are described in [PEP 440](https://peps.python.org/pep-0440/). [Pre-releases](https://peps.python.org/pep-0440/#pre-releases) -: should have versions like `1.7.0rc1` or `1.7.0rc2`. +: should have versions like `1.7.0rc1` or `1.7.0rc2`. [Development versions](https://peps.python.org/pep-0440/#developmental-releases) -: should look like `1.8.0.dev0`, with a commit hash optionally appended as a local version identifier (e.g. `1.8.0.dev2+g00ad77b`). +: should look like `1.8.0.dev0`, with a commit hash optionally appended as a local version identifier (e.g. `1.8.0.dev2+g00ad77b`). (versioning-tooling)= ## Tooling diff --git a/docs/external/index.md b/docs/external/index.md index 35f5471d8b..aee6a6c176 100644 --- a/docs/external/index.md +++ b/docs/external/index.md @@ -15,7 +15,6 @@ Import Scanpy's wrappers to external tools as: import scanpy.external as sce ``` - ```{toctree} :maxdepth: 2 diff --git a/docs/external/preprocessing.md b/docs/external/preprocessing.md index 9f830481b8..a2b0b7a799 100644 --- a/docs/external/preprocessing.md +++ b/docs/external/preprocessing.md @@ -6,6 +6,7 @@ ``` Previously found here, but now part of scanpy’s main API: + - {func}`scanpy.pp.harmony_integrate` - {func}`scanpy.pp.hashsolo` - {func}`scanpy.pp.scrublet` diff --git a/docs/external/tools.md b/docs/external/tools.md index 0ebab4fe85..39ba7717c0 100644 --- a/docs/external/tools.md +++ b/docs/external/tools.md @@ -38,5 +38,4 @@ tl.sandbag tl.cyclone - ``` diff --git a/docs/index.md b/docs/index.md index e00aba8dd4..f325487ee9 100644 --- a/docs/index.md +++ b/docs/index.md @@ -9,7 +9,7 @@ :link: installation :link-type: doc -New to _scanpy_? Check out the installation guide. +New to *scanpy*? Check out the installation guide. ::: :::{grid-item-card} Tutorials {octicon}`play;1em;` diff --git a/docs/installation.md b/docs/installation.md index 448ce0c95a..9b816b0179 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -3,7 +3,6 @@ To use `scanpy` from another project, install it using your favourite environment manager: ::::{tab-set} - :::{tab-item} Hatch (recommended) :sync: hatch @@ -39,7 +38,6 @@ $ pip install scanpy [miniconda]: https://docs.anaconda.com/miniconda/miniconda-install/ [from pypi]: https://pypi.org/project/scanpy ::: - :::: If you use Hatch or pip, the extra `[leiden]` installs two packages that are needed for popular @@ -60,7 +58,6 @@ $ cd scanpy ``` ::::{tab-set} - :::{tab-item} Hatch (recommended) :sync: hatch @@ -103,7 +100,6 @@ $ pip install --group=dev --group=test --group=doc -e . For instructions on how to work with the code, see the {ref}`contribution guide `. ::: - :::: [on github]: https://github.com/scverse/scanpy diff --git a/docs/release-notes/1.10.0.md b/docs/release-notes/1.10.0.md index c36d35e78c..962228fb5f 100644 --- a/docs/release-notes/1.10.0.md +++ b/docs/release-notes/1.10.0.md @@ -58,7 +58,6 @@ Some highlights: - Fix use of {func}`~scanpy.tl.dendrogram` on highly correlated low precision data {pr}`2928` {smaller}`P Angerer` - Fix pytest deprecation warning {pr}`2879` {smaller}`P Angerer` - #### Development Process - Scanpy is now tested against python 3.12 {pr}`2863` {smaller}`ivirshup` diff --git a/docs/release-notes/1.10.1.md b/docs/release-notes/1.10.1.md index 4d403737f9..b4960da4e8 100644 --- a/docs/release-notes/1.10.1.md +++ b/docs/release-notes/1.10.1.md @@ -9,7 +9,6 @@ - Fix `aggregate` when aggregating by more than two groups {pr}`2965` {smaller}`I Virshup` - #### Performance - {func}`~scanpy.pp.scale` now uses numba kernels for `sparse.csr_matrix` and `sparse.csc_matrix` when `zero_center==False` and `mask_obs` is provided. This greatly speed up execution {pr}`2942` {smaller}`S Dicks` diff --git a/docs/release-notes/1.11.0.md b/docs/release-notes/1.11.0.md index e13184b88c..396c0d6ac7 100644 --- a/docs/release-notes/1.11.0.md +++ b/docs/release-notes/1.11.0.md @@ -31,7 +31,9 @@ Release candidates: #### Documentation - {guilabel}`rc1` Improve {func}`~scanpy.pp.harmony_integrate` docs {smaller}`D Kühl` ({pr}`3362`) + - {guilabel}`rc1` Raise {exc}`FutureWarning` when calling deprecated {mod}`scanpy.pp` functions {smaller}`P Angerer` ({pr}`3380`) + - {guilabel}`rc1` {smaller}`P Angerer` ({pr}`3407`) | Deprecate … | in favor of … | diff --git a/docs/release-notes/1.13.0b1.md b/docs/release-notes/1.13.0b1.md index e09d650e4a..eed1617916 100644 --- a/docs/release-notes/1.13.0b1.md +++ b/docs/release-notes/1.13.0b1.md @@ -13,64 +13,65 @@ #### Features - Add {func}`scanpy.pp.normalize_shifted_clr` for PFlog shifted centered log-ratio normalization, a variance-stabilizing, depth-invariant and rank-preserving count transform {cite:p}`Booeshaghi2022`. By default, it estimates negative-binomial overdispersion and uses the Anscombe pseudocount. The complete centered result is stored in `X` or the selected layer. Because CLR centering generally maps zeros to non-zero values, the output is dense. {smaller}`R Baber` ({pr}`4160`) + - Add an `ncols` parameter to {func}`scanpy.pl.paga` so multi-color PAGA plots can be arranged in a configurable grid instead of a single row. {smaller}`A Moradniaei` ({pr}`4325`) + - Rename `mask_var`/`mask_obs` to `mask` in {func}`~scanpy.pp.pca`, {func}`~scanpy.pp.scale`, {func}`~scanpy.tl.rank_genes_groups`, and {func}`~scanpy.experimental.pp.normalize_pearson_residuals_pca`. The new parameter takes {mod}`anndata.acc` references, e.g. `A.var["highly_variable"]` {smaller}`P Angerer` ({pr}`4333`) + - Functions now say where they read from with `use` and where they write to with `out`, taking {mod}`anndata.acc` accessors (e.g. `A.layers["counts"]`) or {meth}`~anndata.acc.AdAcc.resolve`\ able strings (e.g. `"layers.counts"`). A function’s `use` takes what was passed to the `out` of the function producing its input, e.g. `sc.pp.pca(adata, out=A.obsm["p"])` and then `sc.pp.neighbors(adata, use=A.obsm["p"])`: - ```{container} Single input - : `use` is one accessor, deprecating `layer`, `obsm`, `use_rep` and `use_raw`, - e.g. `sc.pp.log1p(adata, use=A.layers["counts"])`. + : `use` is one accessor, deprecating `layer`, `obsm`, `use_rep` and `use_raw`, + e.g. `sc.pp.log1p(adata, use=A.layers["counts"])`. Outputs - : `out` is an accessor to write to (e.g. `sc.tl.umap(adata, out=A.obsm["umap2"])`), - `out=True` to return the result instead (replacing `inplace=False`, `score_name` and `copy`), - or `out=False` (the default) to write it to its default place, - which is the input itself for functions transforming a matrix, e.g. {func}`~scanpy.pp.log1p`. - This deprecates `key_added`. - {func}`~scanpy.pp.highly_variable_genes` only takes `out=True` or `out=False` until there are references to columns of DataFrames in {attr}`~anndata.AnnData.varm` ({issue}`scverse/anndata#2722`). + : `out` is an accessor to write to (e.g. `sc.tl.umap(adata, out=A.obsm["umap2"])`), + `out=True` to return the result instead (replacing `inplace=False`, `score_name` and `copy`), + or `out=False` (the default) to write it to its default place, + which is the input itself for functions transforming a matrix, e.g. {func}`~scanpy.pp.log1p`. + This deprecates `key_added`. + {func}`~scanpy.pp.highly_variable_genes` only takes `out=True` or `out=False` until there are references to columns of DataFrames in {attr}`~anndata.AnnData.varm` ({issue}`scverse/anndata#2722`). Several outputs - : An accessor names the primary output `k`, e.g. `sc.pp.pca(adata, out=A.obsm["p"])`, - and the others follow it: they are named `k` in kinds of places no other output goes to - (`.varm["p"]` and `.uns["p"]`), - and `k_{name}` otherwise (e.g. `sc.pp.neighbors(adata, out=A.obsp["nn"])` writes `.obsp["nn"]` and `.obsp["nn_distances"]`). - This also applies to the primary output’s default place (e.g. `out=A.obsp["connectivities"]` writes `.obsp["connectivities_distances"]`), only `out=False` writes to the default places. - If the primary output goes to `A.X`, the others go to their default places. - A mapping of output names to accessors writes only the outputs it names, - e.g. `out={"connectivities": A.obsp["conns"]}` (typed as e.g. {class}`~scanpy.pp.NeighborsOut`), - and two outputs can’t go to the same place. - `out=True` returns them as a {class}`~typing.NamedTuple` (e.g. {class}`~scanpy.pp.PcaResult`). - For now, {func}`~scanpy.pp.scrublet`, {func}`~scanpy.tl.score_genes_cell_cycle` and {func}`~scanpy.tl.dpt` only take a mapping, - as none of their outputs is the primary one. - Once there are `.uns` accessors ({issue}`scverse/anndata#2657`), they will take `out=A.uns["k"]` and store the derived mapping of accessors in there. + : An accessor names the primary output `k`, e.g. `sc.pp.pca(adata, out=A.obsm["p"])`, + and the others follow it: they are named `k` in kinds of places no other output goes to + (`.varm["p"]` and `.uns["p"]`), + and `k_{name}` otherwise (e.g. `sc.pp.neighbors(adata, out=A.obsp["nn"])` writes `.obsp["nn"]` and `.obsp["nn_distances"]`). + This also applies to the primary output’s default place (e.g. `out=A.obsp["connectivities"]` writes `.obsp["connectivities_distances"]`), only `out=False` writes to the default places. + If the primary output goes to `A.X`, the others go to their default places. + A mapping of output names to accessors writes only the outputs it names, + e.g. `out={"connectivities": A.obsp["conns"]}` (typed as e.g. {class}`~scanpy.pp.NeighborsOut`), + and two outputs can’t go to the same place. + `out=True` returns them as a {class}`~typing.NamedTuple` (e.g. {class}`~scanpy.pp.PcaResult`). + For now, {func}`~scanpy.pp.scrublet`, {func}`~scanpy.tl.score_genes_cell_cycle` and {func}`~scanpy.tl.dpt` only take a mapping, + as none of their outputs is the primary one. + Once there are `.uns` accessors ({issue}`scverse/anndata#2657`), they will take `out=A.uns["k"]` and store the derived mapping of accessors in there. Neighborhood graphs - : Functions using {func}`~scanpy.pp.neighbors`’ results take the graph as `use`, e.g. `sc.tl.umap(adata, use=A.obsp["nn"])`, - deprecating `neighbors_key`, `obsp` and `adjacency` - ({func}`~scanpy.tl.ingest` keeps `neighbors_key` until there are `.uns` accessors). - Distances and parameters are found where {func}`~scanpy.pp.neighbors` stored them alongside the graph, if they exist. - {func}`~scanpy.tl.umap` lays out a graph with more than `2 * n_components` connected components using data: - by default the representation {func}`~scanpy.pp.neighbors` used, otherwise pass e.g. `rep=A.obsm["pca"]`. - {func}`~scanpy.metrics.gearys_c` and {func}`~scanpy.metrics.morans_i` also take the graph as `use`, deprecating `use_graph`, - and their `vals` takes an accessor (e.g. `vals=A.obsm["pca"]`), deprecating `layer`, `obsm` and `obsp`. + : Functions using {func}`~scanpy.pp.neighbors`’ results take the graph as `use`, e.g. `sc.tl.umap(adata, use=A.obsp["nn"])`, + deprecating `neighbors_key`, `obsp` and `adjacency` + ({func}`~scanpy.tl.ingest` keeps `neighbors_key` until there are `.uns` accessors). + Distances and parameters are found where {func}`~scanpy.pp.neighbors` stored them alongside the graph, if they exist. + {func}`~scanpy.tl.umap` lays out a graph with more than `2 * n_components` connected components using data: + by default the representation {func}`~scanpy.pp.neighbors` used, otherwise pass e.g. `rep=A.obsm["pca"]`. + {func}`~scanpy.metrics.gearys_c` and {func}`~scanpy.metrics.morans_i` also take the graph as `use`, deprecating `use_graph`, + and their `vals` takes an accessor (e.g. `vals=A.obsm["pca"]`), deprecating `layer`, `obsm` and `obsp`. Groupings and covariates - : take references like `A.obs["batch"]`: - `batch` replaces `batch_key` in {func}`~scanpy.pp.highly_variable_genes`, {func}`~scanpy.pp.scrublet` and the experimental Pearson residual functions, - {func}`~scanpy.pp.combat`’s `key` and {func}`~scanpy.pp.regress_out`’s `keys` are renamed to `batch` and `covariates`, - {func}`~scanpy.pp.harmony_integrate` takes `batch`, - and `groupby` of {func}`~scanpy.tl.rank_genes_groups`, {func}`~scanpy.tl.filter_rank_genes_groups`, {func}`~scanpy.tl.dendrogram` and {func}`~scanpy.tl.embedding_density` - as well as {func}`~scanpy.tl.paga`’s `groups` accept them. + : take references like `A.obs["batch"]`: + `batch` replaces `batch_key` in {func}`~scanpy.pp.highly_variable_genes`, {func}`~scanpy.pp.scrublet` and the experimental Pearson residual functions, + {func}`~scanpy.pp.combat`’s `key` and {func}`~scanpy.pp.regress_out`’s `keys` are renamed to `batch` and `covariates`, + {func}`~scanpy.pp.harmony_integrate` takes `batch`, + and `groupby` of {func}`~scanpy.tl.rank_genes_groups`, {func}`~scanpy.tl.filter_rank_genes_groups`, {func}`~scanpy.tl.dendrogram` and {func}`~scanpy.tl.embedding_density` + as well as {func}`~scanpy.tl.paga`’s `groups` accept them. Outputs only in `.uns` - : {func}`~scanpy.tl.rank_genes_groups`, {func}`~scanpy.tl.filter_rank_genes_groups`, {func}`~scanpy.tl.dendrogram` and {func}`~scanpy.tl.paga` - take `out=True` to return their results. - Until there are `.uns` accessors ({issue}`scverse/anndata#2657`), - they keep `key_added` (where they had one) and the functions reading their results keep `key`. - ``` + : {func}`~scanpy.tl.rank_genes_groups`, {func}`~scanpy.tl.filter_rank_genes_groups`, {func}`~scanpy.tl.dendrogram` and {func}`~scanpy.tl.paga` + take `out=True` to return their results. + Until there are `.uns` accessors ({issue}`scverse/anndata#2657`), + they keep `key_added` (where they had one) and the functions reading their results keep `key`. Strings passed instead of accessors are {meth}`~anndata.acc.AdAcc.resolve`\ d (e.g. `"obs.batch"`), except where a parameter already took strings with another meaning (e.g. column or `.obsm` key names): diff --git a/docs/release-notes/1.2.1.md b/docs/release-notes/1.2.1.md index 32ffa2357b..5979029098 100644 --- a/docs/release-notes/1.2.1.md +++ b/docs/release-notes/1.2.1.md @@ -3,4 +3,4 @@ #### Plotting of {ref}`pl-generic` marker genes and quality control. -- {func}`~scanpy.pl.highest_expr_genes` for quality control; plot genes with highest mean fraction of cells, similar to `plotQC` of _Scater_ {cite:p}`McCarthy2017` {pr}`169` {smaller}`F Ramirez` +- {func}`~scanpy.pl.highest_expr_genes` for quality control; plot genes with highest mean fraction of cells, similar to `plotQC` of *Scater* {cite:p}`McCarthy2017` {pr}`169` {smaller}`F Ramirez` diff --git a/docs/release-notes/1.3.4.md b/docs/release-notes/1.3.4.md index 35d97159c6..9381bc4647 100644 --- a/docs/release-notes/1.3.4.md +++ b/docs/release-notes/1.3.4.md @@ -3,4 +3,4 @@ - {func}`~scanpy.tl.leiden` wraps the recent graph clustering package by {cite:t}`Traag2019` {smaller}`K Polanski` - {func}`~scanpy.external.pp.bbknn` wraps the recent batch correction package {cite:p}`Polanski2019` {smaller}`K Polanski` -- {func}`~scanpy.pp.calculate_qc_metrics` caculates a number of quality control metrics, similar to `calculateQCMetrics` from _Scater_ {cite:p}`McCarthy2017` {smaller}`I Virshup` +- {func}`~scanpy.pp.calculate_qc_metrics` caculates a number of quality control metrics, similar to `calculateQCMetrics` from *Scater* {cite:p}`McCarthy2017` {smaller}`I Virshup` diff --git a/docs/release-notes/1.3.6.md b/docs/release-notes/1.3.6.md index d2e68f3b86..10e6b7fe80 100644 --- a/docs/release-notes/1.3.6.md +++ b/docs/release-notes/1.3.6.md @@ -6,7 +6,7 @@ - a new plotting gallery for `visualizing-marker-genes` {smaller}`F Ramirez` - tutorials are integrated on ReadTheDocs, `pbmc3k` and `paga-paul15` {smaller}`A Wolf` -#### Interactive exploration of analysis results through _manifold viewers_ +#### Interactive exploration of analysis results through *manifold viewers* - CZI’s [cellxgene] directly reads `.h5ad` files {smaller}`the cellxgene developers` - the [UCSC Single Cell Browser] requires exporting via {func}`~scanpy.external.exporting.cellbrowser` {smaller}`M Haeussler` diff --git a/docs/release-notes/1.4.5.md b/docs/release-notes/1.4.5.md index 125536d376..32e4a69614 100644 --- a/docs/release-notes/1.4.5.md +++ b/docs/release-notes/1.4.5.md @@ -19,6 +19,7 @@ Please install `scanpy==1.4.5.post3` instead of `scanpy==1.4.5`. - webpage overhaul, ecosystem page, release notes, tutorials overhaul {pr}`960` {pr}`966` {smaller}`A Wolf` ```{warning} + - changed default `solver` in {func}`~scanpy.pp.pca` from `auto` to `arpack` - changed default `use_raw` in {func}`~scanpy.tl.score_genes` from `False` to `None` ``` diff --git a/docs/usage-principles.md b/docs/usage-principles.md index 328c59b381..457824dc8a 100644 --- a/docs/usage-principles.md +++ b/docs/usage-principles.md @@ -15,7 +15,7 @@ sc.tl.umap(adata, **tool_params) # embed a neighborhood graph of the data using ``` where `adata` is an {class}`~anndata.AnnData` object. -Each of these calls adds annotation to an expression matrix _X_, +Each of these calls adds annotation to an expression matrix *X*, which stores *n_obs* observations (cells) of *n_vars* variables (genes). For each tool, there typically is an associated plotting function in `sc.pl`: @@ -27,7 +27,7 @@ If you pass `show=False`, a {class}`~matplotlib.axes.Axes` instance is returned and you have all of matplotlib's detailed configuration possibilities. To facilitate writing memory-efficient pipelines, by default, -Scanpy tools operate _inplace_ on `adata` and return `None` – +Scanpy tools operate *inplace* on `adata` and return `None` – this also allows to easily transition to [out-of-memory pipelines]. If you want to return a copy of the {class}`~anndata.AnnData` object and leave the passed `adata` unchanged, pass `copy=True` or `inplace=False`.