diff --git a/docs/release-notes/1.10.2.md b/docs/release-notes/1.10.2.md index 36a977143c..b39ce47b8f 100644 --- a/docs/release-notes/1.10.2.md +++ b/docs/release-notes/1.10.2.md @@ -8,6 +8,7 @@ ```{rubric} Docs ``` +* Document several missing parameters in docstring {pr}`2888` {smaller}`S Cheney` * Fixed incorrect instructions in "testing" dev docs {pr}`2994` {smaller}`I Virshup` * Update marsilea tutorial to use `group_` methods {pr}`3001` {smaller}`I Virshup` * Fixed citations {pr}`3032` {smaller}`P Angerer` diff --git a/scanpy/logging.py b/scanpy/logging.py index 85a7b88f91..168c3b5405 100644 --- a/scanpy/logging.py +++ b/scanpy/logging.py @@ -157,6 +157,11 @@ def print_header(*, file=None): """\ Versions that might influence the numerical results. Matplotlib and Seaborn are excluded from this. + + Parameters + ---------- + file + Optional path for dependency output. """ modules = ["scanpy"] + _DEPENDENCIES_NUMERICS @@ -171,6 +176,11 @@ def print_versions(*, file: IO[str] | None = None): Print versions of imported packages, OS, and jupyter environment. For more options (including rich output) use `session_info.show` directly. + + Parameters + ---------- + file + Optional path for output. """ import session_info @@ -202,6 +212,11 @@ def print_versions(*, file: IO[str] | None = None): def print_version_and_date(*, file=None): """\ Useful for starting a notebook so you see when you started working. + + Parameters + ---------- + file + Optional path for output. """ from . import __version__ @@ -228,7 +243,7 @@ def error( Log message with specific level and return current time. Parameters - ========== + ---------- msg Message to display. time diff --git a/scanpy/plotting/_docs.py b/scanpy/plotting/_docs.py index 899310a08a..0bf363237e 100644 --- a/scanpy/plotting/_docs.py +++ b/scanpy/plotting/_docs.py @@ -43,8 +43,26 @@ Passed to :meth:`~matplotlib.axes.Axes.quiver`\ """ +doc_cm_palette = """\ +color_map + Color map to use for continous variables. Can be a name or a + :class:`~matplotlib.colors.Colormap` instance (e.g. `"magma`", `"viridis"` + or `mpl.cm.cividis`), see :func:`~matplotlib.pyplot.get_cmap`. + If `None`, the value of `mpl.rcParams["image.cmap"]` is used. + The default `color_map` can be set using :func:`~scanpy.set_figure_params`. +palette + Colors to use for plotting categorical annotation groups. + The palette can be a valid :class:`~matplotlib.colors.ListedColormap` name + (`'Set2'`, `'tab20'`, …), a :class:`~cycler.Cycler` object, a dict mapping + categories to colors, or a sequence of colors. Colors must be valid to + matplotlib. (see :func:`~matplotlib.colors.is_color_like`). + If `None`, `mpl.rcParams["axes.prop_cycle"]` is used unless the categorical + variable already has colors stored in `adata.uns["{var}_colors"]`. + If provided, values of `adata.uns["{var}_colors"]` will be set.\ +""" + # Docs for pl.scatter -doc_scatter_basic = """\ +doc_scatter_basic = f"""\ sort_order For continuous annotations used as color parameter, plot data points with higher values on top of others. @@ -81,21 +99,7 @@ Point size. If `None`, is automatically computed as 120000 / n_cells. Can be a sequence containing the size for each cell. The order should be the same as in adata.obs. -color_map - Color map to use for continous variables. Can be a name or a - :class:`~matplotlib.colors.Colormap` instance (e.g. `"magma`", `"viridis"` - or `mpl.cm.cividis`), see :func:`~matplotlib.pyplot.get_cmap`. - If `None`, the value of `mpl.rcParams["image.cmap"]` is used. - The default `color_map` can be set using :func:`~scanpy.set_figure_params`. -palette - Colors to use for plotting categorical annotation groups. - The palette can be a valid :class:`~matplotlib.colors.ListedColormap` name - (`'Set2'`, `'tab20'`, …), a :class:`~cycler.Cycler` object, a dict mapping - categories to colors, or a sequence of colors. Colors must be valid to - matplotlib. (see :func:`~matplotlib.colors.is_color_like`). - If `None`, `mpl.rcParams["axes.prop_cycle"]` is used unless the categorical - variable already has colors stored in `adata.uns["{var}_colors"]`. - If provided, values of `adata.uns["{var}_colors"]` will be set. +{doc_cm_palette} na_color Color to use for null or masked values. Can be anything matplotlib accepts as a color. Used for all points if `color=None`. @@ -179,13 +183,17 @@ for instance: the maximum and minimum values (e.g. `vmin=-2, vmax=5`).\ """ -doc_show_save_ax = """\ +doc_show_save = """\ show Show the plot, do not return axis. save If `True` or a `str`, save the figure. A string is appended to the default filename. - Infer the filetype if ending on {`'.pdf'`, `'.png'`, `'.svg'`}. + Infer the filetype if ending on {`'.pdf'`, `'.png'`, `'.svg'`}.\ +""" + +doc_show_save_ax = f"""\ +{doc_show_save} ax A matplotlib axes object. Only works if plotting a single component.\ """ diff --git a/scanpy/plotting/_tools/__init__.py b/scanpy/plotting/_tools/__init__.py index d8137aff67..dceb779fd8 100644 --- a/scanpy/plotting/_tools/__init__.py +++ b/scanpy/plotting/_tools/__init__.py @@ -19,10 +19,12 @@ from ...get import rank_genes_groups_df from .._anndata import ranking from .._docs import ( + doc_cm_palette, doc_panels, doc_rank_genes_groups_plot_args, doc_rank_genes_groups_values_to_plot, doc_scatter_embedding, + doc_show_save, doc_show_save_ax, doc_vbound_percentile, ) @@ -265,6 +267,7 @@ def dpt_timeseries( @old_positionals("color_map", "palette", "show", "save", "marker") +@_doc_params(cm_palette=doc_cm_palette, show_save=doc_show_save) def dpt_groups_pseudotime( adata: AnnData, *, @@ -274,7 +277,18 @@ def dpt_groups_pseudotime( save: bool | str | None = None, marker: str | Sequence[str] = ".", ): - """Plot groups and pseudotime.""" + """\ + Plot groups and pseudotime. + + Parameters + ---------- + adata + Annotated data matrix. + {cm_palette} + {show_save} + marker + Marker style. See :mod:`~matplotlib.markers` for details. + """ _, (ax_grp, ax_ord) = plt.subplots(2, 1) timeseries_subplot( adata.obs["dpt_groups"].cat.codes, diff --git a/scanpy/preprocessing/_recipes.py b/scanpy/preprocessing/_recipes.py index 40d697f4c7..4579739939 100644 --- a/scanpy/preprocessing/_recipes.py +++ b/scanpy/preprocessing/_recipes.py @@ -91,6 +91,17 @@ def recipe_seurat( Expects non-logarithmized data. If using logarithmized data, pass `log=False`. + + Parameters + ---------- + adata + Annotated data matrix. + log + Logarithmize data? + plot + Show a plot of the gene dispersion vs. mean relation. + copy + Return a copy if true. """ if copy: adata = adata.copy()