"""\
Shared docstrings for plotting function parameters.
"""


doc_adata_color_etc = """\
adata
    Annotated data matrix.
color
    Keys for annotations of observations/cells or variables/genes, e.g.,
    `'ann1'` or `['ann1', 'ann2']`.
gene_symbols
    Column name in `.var` DataFrame that stores gene symbols. By default `var_names`
    refer to the index column of the `.var` DataFrame. Setting this option allows
    alternative names to be used.
use_raw
    Use `.raw` attribute of `adata` for coloring with gene expression. If `None`,
    defaults to `True` if `layer` isn't provided and `adata.raw` is present.
layer
    Name of the AnnData object layer that wants to be plotted. By default
    adata.raw.X is plotted. If `use_raw=False` is set, then `adata.X` is plotted.
    If `layer` is set to a valid layer name, then the layer is plotted. `layer`
    takes precedence over `use_raw`.\
"""

doc_edges_arrows = """\
edges
    Show edges.
edges_width
    Width of edges.
edges_color
    Color of edges. See :func:`~networkx.drawing.nx_pylab.draw_networkx_edges`.
neighbors_key
    Where to look for neighbors connectivities.
    If not specified, this looks .obsp['connectivities'] for connectivities
    (default storage place for pp.neighbors).
    If specified, this looks
    .obsp[.uns[neighbors_key]['connectivities_key']] for connectivities.
arrows
    Show arrows (deprecated in favour of `scvelo.pl.velocity_embedding`).
arrows_kwds
    Passed to :meth:`~matplotlib.axes.Axes.quiver`\
"""

# Docs for pl.scatter
doc_scatter_basic = """\
sort_order
    For continuous annotations used as color parameter, plot data points
    with higher values on top of others.
groups
    Restrict to a few categories in categorical observation annotation.
    The default is not to restrict to any groups.
components
    For instance, `['1,2', '2,3']`. To plot all available components use
    `components='all'`.
projection
    Projection of plot (default: `'2d'`).
legend_loc
    Location of legend, either `'on data'`, `'right margin'` or a valid keyword
    for the `loc` parameter of :class:`~matplotlib.legend.Legend`.
legend_fontsize
    Numeric size in pt or string describing the size.
    See :meth:`~matplotlib.text.Text.set_fontsize`.
legend_fontweight
    Legend font weight. A numeric value in range 0-1000 or a string.
    Defaults to `'bold'` if `legend_loc == 'on data'`, otherwise to `'normal'`.
    See :meth:`~matplotlib.text.Text.set_fontweight`.
legend_fontoutline
    Line width of the legend font outline in pt. Draws a white outline using
    the path effect :class:`~matplotlib.patheffects.withStroke`.
size
    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.cm.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.
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`.
na_in_legend
    If there are missing values, whether they get an entry in the legend. Currently
    only implemented for categorical legends.
frameon
    Draw a frame around the scatter plot. Defaults to value set in
    :func:`~scanpy.set_figure_params`, defaults to `True`.
title
    Provide title for panels either as string or list of strings,
    e.g. `['title1', 'title2', ...]`.
"""

doc_vbound_percentile = """\
vmin
    The value representing the lower limit of the color scale. Values smaller than vmin are plotted
    with the same color as vmin. vmin can be a number, a string, a function or `None`. If
    vmin is a string and has the format `pN`, this is interpreted as a vmin=percentile(N).
    For example vmin='p1.5' is interpreted as the 1.5 percentile. If vmin is function, then
    vmin is interpreted as the return value of the function over the list of values to plot.
    For example to set vmin tp the mean of the values to plot, `def my_vmin(values): return
    np.mean(values)` and then set `vmin=my_vmin`. If vmin is None (default) an automatic
    minimum value is used as defined by matplotlib `scatter` function. When making multiple
    plots, vmin can be a list of values, one for each plot. For example `vmin=[0.1, 'p1', None, my_vmin]`
vmax
    The value representing the upper limit of the color scale. The format is the same as for `vmin`.
vcenter
    The value representing the center of the color scale. Useful for diverging colormaps.
    The format is the same as for `vmin`.
    Example: sc.pl.umap(adata, color='TREM2', vcenter='p50', cmap='RdBu_r')\
"""

doc_vboundnorm = """\
vmin
    The value representing the lower limit of the color scale. Values smaller than vmin are plotted
    with the same color as vmin.
vmax
    The value representing the upper limit of the color scale. Values larger than vmax are plotted
    with the same color as vmax.
vcenter
    The value representing the center of the color scale. Useful for diverging colormaps.
norm
    Custom color normalization object from matplotlib. See
    `https://matplotlib.org/stable/tutorials/colors/colormapnorms.html` for details.\
"""

doc_outline = """\
add_outline
    If set to True, this will add a thin border around groups of dots. In some situations
    this can enhance the aesthetics of the resulting image
outline_color
    Tuple with two valid color names used to adjust the add_outline. The first color is the
    border color (default: black), while the second color is a gap color between the
    border color and the scatter dot (default: white).
outline_width
    Tuple with two width numbers used to adjust the outline. The first value is the width
    of the border color as a fraction of the scatter dot size (default: 0.3). The second value is
    width of the gap color (default: 0.05).\
"""

doc_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.
return_fig
    Return the matplotlib figure.\
"""

# Docs for pl.pca, pl.tsne, … (everything in _tools.scatterplots)
doc_scatter_embedding = f"""\
{doc_scatter_basic}
{doc_vbound_percentile}
{doc_outline}
{doc_panels}
kwargs
    Arguments to pass to :func:`matplotlib.pyplot.scatter`,
    for instance: the maximum and minimum values (e.g. `vmin=-2, vmax=5`).\
"""

doc_show_save_ax = """\
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'`}.
ax
    A matplotlib axes object. Only works if plotting a single component.\
"""

doc_common_plot_args = """\
adata
    Annotated data matrix.
var_names
    `var_names` should be a valid subset of `adata.var_names`.
    If `var_names` is a mapping, then the key is used as label
    to group the values (see `var_group_labels`). The mapping values
    should be sequences of valid `adata.var_names`. In this
    case either coloring or 'brackets' are used for the grouping
    of var names depending on the plot. When `var_names` is a mapping,
    then the `var_group_labels` and `var_group_positions` are set.
groupby
    The key of the observation grouping to consider.
use_raw
    Use `raw` attribute of `adata` if present.
log
    Plot on logarithmic axis.
num_categories
    Only used if groupby observation is not categorical. This value
    determines the number of groups into which the groupby observation
    should be subdivided.
categories_order
    Order in which to show the categories. Note: add_dendrogram or add_totals
    can change the categories order.
figsize
    Figure size when `multi_panel=True`.
    Otherwise the `rcParam['figure.figsize]` value is used.
    Format is (width, height)
dendrogram
    If True or a valid dendrogram key, a dendrogram based on the hierarchical
    clustering between the `groupby` categories is added.
    The dendrogram information is computed using :func:`scanpy.tl.dendrogram`.
    If `tl.dendrogram` has not been called previously the function is called
    with default parameters.
gene_symbols
    Column name in `.var` DataFrame that stores gene symbols.
    By default `var_names` refer to the index column of the `.var` DataFrame.
    Setting this option allows alternative names to be used.
var_group_positions
    Use this parameter to highlight groups of `var_names`.
    This will draw a 'bracket' or a color block between the given start and end
    positions. If the parameter `var_group_labels` is set, the corresponding
    labels are added on top/left. E.g. `var_group_positions=[(4,10)]`
    will add a bracket between the fourth `var_name` and the tenth `var_name`.
    By giving more positions, more brackets/color blocks are drawn.
var_group_labels
    Labels for each of the `var_group_positions` that want to be highlighted.
var_group_rotation
    Label rotation degrees.
    By default, labels larger than 4 characters are rotated 90 degrees.
layer
    Name of the AnnData object layer that wants to be plotted. By default adata.raw.X is plotted.
    If `use_raw=False` is set, then `adata.X` is plotted. If `layer` is set to a valid layer name,
    then the layer is plotted. `layer` takes precedence over `use_raw`.\
"""

doc_rank_genes_groups_plot_args = """\
adata
    Annotated data matrix.
groups
    The groups for which to show the gene ranking.
n_genes
    Number of genes to show. This can be a negative number to show for
    example the down regulated genes. eg: num_genes=-10. Is ignored if
    `gene_names` is passed.
gene_symbols
    Column name in `.var` DataFrame that stores gene symbols. By default `var_names`
    refer to the index column of the `.var` DataFrame. Setting this option allows
    alternative names to be used.
groupby
    The key of the observation grouping to consider. By default,
    the groupby is chosen from the rank genes groups parameter but
    other groupby options can be used.  It is expected that
    groupby is a categorical. If groupby is not a categorical observation,
    it would be subdivided into `num_categories` (see :func:`~scanpy.pl.dotplot`).
min_logfoldchange
    Value to filter genes in groups if their logfoldchange is less than the
    min_logfoldchange
key
    Key used to store the ranking results in `adata.uns`.\
"""

doc_rank_genes_groups_values_to_plot = """\
values_to_plot
    Instead of the mean gene value, plot the values computed by `sc.rank_genes_groups`.
    The options are: ['scores', 'logfoldchanges', 'pvals', 'pvals_adj',
    'log10_pvals', 'log10_pvals_adj']. When plotting logfoldchanges a divergent
    colormap is recommended. See examples below.
var_names
    Genes to plot. Sometimes is useful to pass a specific list of var names (e.g. genes)
    to check their fold changes or p-values, instead of the top/bottom genes. The
    var_names could be a dictionary or a list as in :func:`~scanpy.pl.dotplot` or
    :func:`~scanpy.pl.matrixplot`. See examples below.\
"""

doc_scatter_spatial = """\
library_id
    library_id for Visium data, e.g. key in `adata.uns["spatial"]`.
img_key
    Key for image data, used to get `img` and `scale_factor` from `"images"`
    and `"scalefactors"` entires for this library. To use spatial coordinates,
    but not plot an image, pass `img_key=None`.
img
    image data to plot, overrides `img_key`.
scale_factor
    Scaling factor used to map from coordinate space to pixel space.
    Found by default if `library_id` and `img_key` can be resolved.
    Otherwise defaults to `1.`.
spot_size
    Diameter of spot (in coordinate space) for each point. Diameter
    in pixels of the spots will be `size * spot_size * scale_factor`.
    This argument is required if it cannot be resolved from library info.
crop_coord
    Coordinates to use for cropping the image (left, right, top, bottom).
    These coordinates are expected to be in pixel space (same as `basis`)
    and will be transformed by `scale_factor`.
    If not provided, image is automatically cropped to bounds of `basis`,
    plus a border.
alpha_img
    Alpha value for image.
bw
    Plot image data in gray scale.\
"""
