Repository: scverse/scanpy

Issue:
Documentation for pl.scatter
Hi,

Some of the parameters documented online for `pl.scatter` are not accepted by the method: `ncols`, `wspace`, `hspace`. And some are not documented: `right_margin`, `left_margin`.

The difference seems to come from the parameters described in `{scatter_bulk}` and used for `pl.scatter` documentation.

What should be fixed `scatter_bulk` or inputs for `pl.scatter`?

Bérénice




Discussion:
Hi Bérénice, ncols, wspace and hspace should work although they are only
meaningful when more than one plot is present. I think that right_margin
and left_margin were used in the initial implementation but no longer.

On Mon, Feb 4, 2019 at 9:50 AM Bérénice Batut <notifications@github.com>
wrote:

> Hi,
>
> Some of the parameters documented online for pl.scatter are not accepted
> by the method: ncols, wspace, hspace. And some are not documented:
> right_margin, left_margin.
>
> The difference seems to come from the parameters described in
> {scatter_bulk} and used for pl.scatter documentation.
>
> What should be fixed scatter_bulk or inputs for pl.scatter?
>
> Bérénice
>
> —
> You are receiving this because you are subscribed to this thread.
> Reply to this email directly, view it on GitHub
> <https://github.com/theislab/scanpy/issues/458>, or mute the thread
> <https://github.com/notifications/unsubscribe-auth/AEu_1bLyz9mimlEZzQ3hbnyiW45MtBHJks5vJ_Q_gaJpZM4agxAk>
> .
>

`right_margin` and `left_margin` are still listed as parameters for `pl.scatter`: 

https://github.com/theislab/scanpy/blob/c15a5e8763097082c82cd8ef6fee697954c487dc/scanpy/plotting/_anndata.py#L49

And `ncols`, `wspace` and `hspace` are not accepted (with the current version on conda) 😟 
I think that there is no up to date Conda installation. Only Pip. The current version is 1.3.7

 

> On 4 Feb 2019, at 10:26, Bérénice Batut <notifications@github.com> wrote:
> 
> right_margin and left_margin are still listed as parameters for pl.scatter:
> 
> https://github.com/theislab/scanpy/blob/c15a5e8763097082c82cd8ef6fee697954c487dc/scanpy/plotting/_anndata.py#L49
> 
> And ncols, wspace and hspace are not accepted (with the current version on conda) 😟
> 
> —
> You are receiving this because you commented.
> Reply to this email directly, view it on GitHub, or mute the thread.

We're not maintaining the bioconda version, but it looks as if it was up to date: https://bioconda.github.io/recipes/scanpy/README.html

How is it working, anyways? Does somebody know? Does it automatically pull from PyPI?
We have the ![](https://img.shields.io/badge/install%20with-bioconda-brightgreen.svg) badge. I think we should remove that if we’re not actually recommending installation that way. If there’s a “[On ]bioconda” badge to put next to the PyPI badge, I’d prefer that.

/edit: The badges are custom, we can control the text. I replaced it to match the PyPI badge, except that we can’t get a version, so I put a cute snake: ![](https://img.shields.io/pypi/v/scanpy.svg) ![](https://img.shields.io/badge/bioconda-🐍-blue.svg)
> How is it working, anyways? Does somebody know? Does it automatically pull from PyPI?

yes: bioconda/bioconda-recipes#12958

> This pull request was automatically generated by [bioconda-utils](https://github.com/bioconda/bioconda-utils).
Thanks! Makes sense! (Both the badge and the automatic update from PyPI).
I also just realised that `pl.scatter` does not take `ncols` as an argument.  I am also using scanpy v1.4 from bioconda. The online documentation also does not mention ncols as an argument:
`scanpy.pl.scatter(adata, x=None, y=None, color=None, use_raw=None, layers='X', sort_order=True, alpha=None, basis=None, groups=None, components=None, projection='2d', legend_loc='right margin', legend_fontsize=None, legend_fontweight=None, color_map=None, palette=None, frameon=None, right_margin=None, left_margin=None, size=None, title=None, show=None, save=None, ax=None)` (copy-paste from https://icb-scanpy.readthedocs-hosted.com/en/latest/api/scanpy.pl.scatter.html), but it does mention `ncols` below in the description.

`pl.scatter` is, unfortunately, not in the best shape anymore. Since Fidel rewrote a large part of the plotting API, it's not used by any of the frequently used embeddings scatters anymore and would need to be simplified a lot, before actually adding new functionality (like `ncols`).

Would you mind correcting the docs? What are you using `pl.scatter` for?
Sure, I can have a look at the docs. I've been using it because of the `layers` argument since `pl.umap` does not seem to have it.
@fabianrost84 The 'layers' were not added to anndata until recently and had not been implemented in all functions. However, adding this functionality to the different scatter plot functions is straightforward.

Let me prepare a quick PR.


As @bebatut pointed out, `pl.scatter` uses `doc_scatter_bulk` for the documentation. It does not seem to make sense to remove `ncols` from `doc_scatter_bulk` as it is used for `pl.umap` and so on.
How should the docs for `pl.scatter` be corrected? Should we remove `doc_scatter_bulk` and copy-paste the relevant documentation from `doc_scatter_bulk` to the `pl.scatter` doc string? At least until `pl.scatter` is in good shape again.
@fabianrost84 The best would be to remove `doc_scatter_bulk`  and copy paste the relevant documentation.
> copy paste

please never say those words when speaking about code again :stuck_out_tongue_winking_eye: 

No but seriously: There’s at least 6 reasons not to do that and to introduce a second (temporary) variable instead: https://github.com/theislab/scanpy/pull/557#issuecomment-476512533

Resolving patch:
diff --git a/scanpy/plotting/_anndata.py b/scanpy/plotting/_anndata.py
--- a/scanpy/plotting/_anndata.py
+++ b/scanpy/plotting/_anndata.py
@@ -17,7 +17,7 @@
 from . import _utils as utils
 from ._utils import scatter_base, scatter_group, setup_axes
 from ..utils import sanitize_anndata, doc_params
-from ._docs import doc_scatter_bulk, doc_show_save_ax, doc_common_plot_args
+from ._docs import doc_scatter_temp, doc_show_save_ax, doc_common_plot_args
 
 VALID_LEGENDLOCS = {
     'none', 'right margin', 'on data', 'on data export', 'best', 'upper right', 'upper left',
@@ -26,7 +26,7 @@
 }
 
 
-@doc_params(scatter_bulk=doc_scatter_bulk, show_save_ax=doc_show_save_ax)
+@doc_params(scatter_temp=doc_scatter_temp, show_save_ax=doc_show_save_ax)
 def scatter(
         adata,
         x=None,
@@ -78,7 +78,7 @@ def scatter(
         `(layers, layers, layers)`.
     basis : {{'pca', 'tsne', 'umap', 'diffmap', 'draw_graph_fr', etc.}}
         String that denotes a plotting tool that computed coordinates.
-    {scatter_bulk}
+    {scatter_temp}
     {show_save_ax}
 
     Returns
diff --git a/scanpy/plotting/_docs.py b/scanpy/plotting/_docs.py
--- a/scanpy/plotting/_docs.py
+++ b/scanpy/plotting/_docs.py
@@ -32,7 +32,7 @@
 """
 
 
-doc_scatter_bulk = """\
+_doc_scatter_common = """\
 sort_order
     For continuous annotations used as color parameter, plot data points
     with higher values on top of others.
@@ -69,12 +69,16 @@
 frameon
     Draw a frame around the scatter plot. Defaults to value set in
     :func:`~scanpy.api.tl.set_figure_params`, defaults to `True`.
+"""
+_doc_scatter_panels = """\
 ncols
     Number of panels per row.
 wspace
     Adjust the width of the space between multiple panels.
 hspace
     Adjust the height of the space between multiple panels.
+"""
+_doc_scatter_meta = """\
 title
     Provide title for panels either as string or list of strings,
     e.g. `['title1', 'title2', ...]`.
@@ -85,6 +89,11 @@
     Return the matplotlib figure.\
 """
 
+# temporarily add a special variable doc_scatter_temp for pl.scatter
+# because currently pl.scatter does not accept ncols, wspace, and hspace
+doc_scatter_temp = _doc_scatter_common + _doc_scatter_meta
+doc_scatter_bulk = _doc_scatter_common + _doc_scatter_panels + _doc_scatter_meta
+
 
 doc_show_save_ax = """\
 show


Test patch: