diff --git a/mkdocs.yml b/mkdocs.yml index c92823309e..523322efff 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -13,7 +13,7 @@ plugins: handlers: python: options: - docstring_style: google + docstring_style: numpy show_source: false show_root_heading: true show_root_toc_entry: true diff --git a/plotly/express/_chart_types.py b/plotly/express/_chart_types.py index 9ec2b4a6a6..cfcabb319e 100644 --- a/plotly/express/_chart_types.py +++ b/plotly/express/_chart_types.py @@ -1,7 +1,6 @@ from warnings import warn from ._core import make_figure -from ._doc import make_docstring import plotly.graph_objs as go _wide_mode_xy_append = [ @@ -65,13 +64,247 @@ def scatter( """ In a scatter plot, each row of `data_frame` is represented by a symbol mark in 2D space. + + Parameters + ---------- + data_frame : DataFrame or array-like or dict + This argument needs to be passed for column names (and not keyword + names) to be used. Array-like and dict are transformed internally to a + pandas DataFrame. Optional: if missing, a DataFrame gets constructed + under the hood using the other arguments. + x : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + position marks along the x axis in cartesian coordinates. Either `x` or + `y` can optionally be a list of column references or array_likes, in + which case the data will be treated as if it were 'wide' rather than + 'long'. + y : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + position marks along the y axis in cartesian coordinates. Either `x` or + `y` can optionally be a list of column references or array_likes, in + which case the data will be treated as if it were 'wide' rather than + 'long'. + color : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign color to marks. + symbol : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign symbols to marks. + size : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign mark sizes. + hover_name : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like appear in bold + in the hover tooltip. + hover_data : str, or list of str or int, or Series or array-like, or dict + Either a name or list of names of columns in `data_frame`, or pandas + Series, or array_like objects or a dict with column names as keys, with + values True (for default formatting) False (in order to remove this + column from hover information), or a formatting string, for example + ':.3f' or '|%a' or list-like data to appear in the hover tooltip or + tuples with a bool or formatting string as first element, and list-like + data to appear in hover as second element Values from these columns + appear as extra data in the hover tooltip. + custom_data : str, or list of str or int, or Series or array-like + Either name or list of names of columns in `data_frame`, or pandas + Series, or array_like objects Values from these columns are extra data, + to be used in widgets or Dash callbacks for example. This data is not + user-visible but is included in events emitted by the figure (lasso + selection etc.) + text : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like appear in the + figure as text labels. + facet_row : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign marks to facetted subplots in the vertical direction. + facet_col : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign marks to facetted subplots in the horizontal direction. + facet_col_wrap : int + Maximum number of facet columns. Wraps the column variable at this + width, so that the column facets span multiple rows. Ignored if 0, and + forced to 0 if `facet_row` or a `marginal` is set. + facet_row_spacing : float between 0 and 1 + Spacing between facet rows, in paper units. Default is 0.03 or 0.07 + when facet_col_wrap is used. + facet_col_spacing : float between 0 and 1 + Spacing between facet columns, in paper units Default is 0.02. + error_x : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + size x-axis error bars. If `error_x_minus` is `None`, error bars will + be symmetrical, otherwise `error_x` is used for the positive direction + only. + error_x_minus : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + size x-axis error bars in the negative direction. Ignored if `error_x` + is `None`. + error_y : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + size y-axis error bars. If `error_y_minus` is `None`, error bars will + be symmetrical, otherwise `error_y` is used for the positive direction + only. + error_y_minus : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + size y-axis error bars in the negative direction. Ignored if `error_y` + is `None`. + animation_frame : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign marks to animation frames. + animation_group : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + provide object-constancy across animation frames: rows with matching + `animation_group`s will be treated as if they describe the same object + in each frame. + category_orders : dict with str keys and list of str values (default `{}`) + By default, in Python 3.6+, the order of categorical values in axes, + legends and facets depends on the order in which these values are first + encountered in `data_frame` (and no order is guaranteed by default in + Python below 3.6). This parameter is used to force a specific ordering + of values per column. The keys of this dict should correspond to column + names, and the values should be lists of strings corresponding to the + specific display order desired. + labels : dict with str keys and str values (default `{}`) + By default, column names are used in the figure for axis titles, legend + entries and hovers. This parameter allows this to be overridden. The + keys of this dict should correspond to column names, and the values + should correspond to the desired label to be displayed. + orientation : str, one of `'h'` for horizontal or `'v'` for vertical. + (default `'v'` if `x` and `y` are provided and both continuous or both + categorical, otherwise `'v'`(`'h'`) if `x`(`y`) is categorical and + `y`(`x`) is continuous, otherwise `'v'`(`'h'`) if only `x`(`y`) is + provided) + color_discrete_sequence : list of str + Strings should define valid CSS-colors. When `color` is set and the + values in the corresponding column are not numeric, values in that + column are assigned colors by cycling through `color_discrete_sequence` + in the order described in `category_orders`, unless the value of + `color` is a key in `color_discrete_map`. Various useful color + sequences are available in the `plotly.express.colors` submodules, + specifically `plotly.express.colors.qualitative`. + color_discrete_map : dict with str keys and str values (default `{}`) + String values should define valid CSS-colors Used to override + `color_discrete_sequence` to assign a specific colors to marks + corresponding with specific values. Keys in `color_discrete_map` should + be values in the column denoted by `color`. Alternatively, if the + values of `color` are valid colors, the string `'identity'` may be + passed to cause them to be used directly. + color_continuous_scale : list of str + Strings should define valid CSS-colors This list is used to build a + continuous color scale when the column denoted by `color` contains + numeric data. Various useful color scales are available in the + `plotly.express.colors` submodules, specifically + `plotly.express.colors.sequential`, `plotly.express.colors.diverging` + and `plotly.express.colors.cyclical`. + range_color : list of two numbers + If provided, overrides auto-scaling on the continuous color scale. + color_continuous_midpoint : number (default `None`) + If set, computes the bounds of the continuous color scale to have the + desired midpoint. Setting this value is recommended when using + `plotly.express.colors.diverging` color scales as the inputs to + `color_continuous_scale`. + symbol_sequence : list of str + Strings should define valid plotly.js symbols. When `symbol` is set, + values in that column are assigned symbols by cycling through + `symbol_sequence` in the order described in `category_orders`, unless + the value of `symbol` is a key in `symbol_map`. + symbol_map : dict with str keys and str values (default `{}`) + String values should define plotly.js symbols Used to override + `symbol_sequence` to assign a specific symbols to marks corresponding + with specific values. Keys in `symbol_map` should be values in the + column denoted by `symbol`. Alternatively, if the values of `symbol` + are valid symbol names, the string `'identity'` may be passed to cause + them to be used directly. + opacity : float + Value between 0 and 1. Sets the opacity for markers. + size_max : int (default `20`) + Set the maximum mark size when using `size`. + marginal_x : str + One of `'rug'`, `'box'`, `'violin'`, or `'histogram'`. If set, a + horizontal subplot is drawn above the main plot, visualizing the + x-distribution. + marginal_y : str + One of `'rug'`, `'box'`, `'violin'`, or `'histogram'`. If set, a + vertical subplot is drawn to the right of the main plot, visualizing + the y-distribution. + trendline : str + One of `'ols'`, `'lowess'`, `'rolling'`, `'expanding'` or `'ewm'`. If + `'ols'`, an Ordinary Least Squares regression line will be drawn for + each discrete-color/symbol group. If `'lowess`', a Locally Weighted + Scatterplot Smoothing line will be drawn for each discrete-color/symbol + group. If `'rolling`', a Rolling (e.g. rolling average, rolling median) + line will be drawn for each discrete-color/symbol group. If + `'expanding`', an Expanding (e.g. expanding average, expanding sum) + line will be drawn for each discrete-color/symbol group. If `'ewm`', an + Exponentially Weighted Moment (e.g. exponentially-weighted moving + average) line will be drawn for each discrete-color/symbol group. See + the docstrings for the functions in + `plotly.express.trendline_functions` for more details on these + functions and how to configure them with the `trendline_options` + argument. + trendline_options : dict + Options passed as the first argument to the function from + `plotly.express.trendline_functions` named in the `trendline` + argument. + trendline_color_override : str + Valid CSS color. If provided, and if `trendline` is set, all trendlines + will be drawn in this color rather than in the same color as the traces + from which they draw their inputs. + trendline_scope : str (one of `'trace'` or `'overall'`, default `'trace'`) + If `'trace'`, then one trendline is drawn per trace (i.e. per color, + symbol, facet, animation frame etc) and if `'overall'` then one + trendline is computed for the entire dataset, and replicated across all + facets. + log_x : boolean (default `False`) + If `True`, the x-axis is log-scaled in cartesian coordinates. + log_y : boolean (default `False`) + If `True`, the y-axis is log-scaled in cartesian coordinates. + range_x : list of two numbers + If provided, overrides auto-scaling on the x-axis in cartesian + coordinates. + range_y : list of two numbers + If provided, overrides auto-scaling on the y-axis in cartesian + coordinates. + render_mode : str + One of `'auto'`, `'svg'` or `'webgl'`, default `'auto'` Controls the + browser API used to draw marks. `'svg'` is appropriate for figures of + less than 1000 data points, and will allow for fully-vectorized output. + `'webgl'` is likely necessary for acceptable performance above 1000 + points but rasterizes part of the output. `'auto'` uses heuristics to + choose the mode. + title : str + The figure title. + subtitle : str + The figure subtitle. + template : str or dict or plotly.graph_objects.layout.Template instance + The figure template name (must be a key in plotly.io.templates) or + definition. + width : int (default `None`) + The figure width in pixels. + height : int (default `None`) + The figure height in pixels. + + Returns + ------- + plotly.graph_objects.Figure """ return make_figure(args=locals(), constructor=go.Scatter) -scatter.__doc__ = make_docstring(scatter, append_dict=_cartesian_append_dict) - - def density_contour( data_frame=None, x=None, @@ -117,6 +350,194 @@ def density_contour( In a density contour plot, rows of `data_frame` are grouped together into contour marks to visualize the 2D distribution of an aggregate function `histfunc` (e.g. the count or sum) of the value `z`. + + Parameters + ---------- + data_frame : DataFrame or array-like or dict + This argument needs to be passed for column names (and not keyword + names) to be used. Array-like and dict are transformed internally to a + pandas DataFrame. Optional: if missing, a DataFrame gets constructed + under the hood using the other arguments. + x : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + position marks along the x axis in cartesian coordinates. Either `x` or + `y` can optionally be a list of column references or array_likes, in + which case the data will be treated as if it were 'wide' rather than + 'long'. + y : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + position marks along the y axis in cartesian coordinates. Either `x` or + `y` can optionally be a list of column references or array_likes, in + which case the data will be treated as if it were 'wide' rather than + 'long'. + z : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + position marks along the z axis in cartesian coordinates. For + `density_heatmap` and `density_contour` these values are used as the + inputs to `histfunc`. + color : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign color to marks. + facet_row : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign marks to facetted subplots in the vertical direction. + facet_col : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign marks to facetted subplots in the horizontal direction. + facet_col_wrap : int + Maximum number of facet columns. Wraps the column variable at this + width, so that the column facets span multiple rows. Ignored if 0, and + forced to 0 if `facet_row` or a `marginal` is set. + facet_row_spacing : float between 0 and 1 + Spacing between facet rows, in paper units. Default is 0.03 or 0.07 + when facet_col_wrap is used. + facet_col_spacing : float between 0 and 1 + Spacing between facet columns, in paper units Default is 0.02. + hover_name : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like appear in bold + in the hover tooltip. + hover_data : str, or list of str or int, or Series or array-like, or dict + Either a name or list of names of columns in `data_frame`, or pandas + Series, or array_like objects or a dict with column names as keys, with + values True (for default formatting) False (in order to remove this + column from hover information), or a formatting string, for example + ':.3f' or '|%a' or list-like data to appear in the hover tooltip or + tuples with a bool or formatting string as first element, and list-like + data to appear in hover as second element Values from these columns + appear as extra data in the hover tooltip. + animation_frame : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign marks to animation frames. + animation_group : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + provide object-constancy across animation frames: rows with matching + `animation_group`s will be treated as if they describe the same object + in each frame. + category_orders : dict with str keys and list of str values (default `{}`) + By default, in Python 3.6+, the order of categorical values in axes, + legends and facets depends on the order in which these values are first + encountered in `data_frame` (and no order is guaranteed by default in + Python below 3.6). This parameter is used to force a specific ordering + of values per column. The keys of this dict should correspond to column + names, and the values should be lists of strings corresponding to the + specific display order desired. + labels : dict with str keys and str values (default `{}`) + By default, column names are used in the figure for axis titles, legend + entries and hovers. This parameter allows this to be overridden. The + keys of this dict should correspond to column names, and the values + should correspond to the desired label to be displayed. + orientation : str, one of `'h'` for horizontal or `'v'` for vertical. + (default `'v'` if `x` and `y` are provided and both continous or both + categorical, otherwise `'v'`(`'h'`) if `x`(`y`) is categorical and + `y`(`x`) is continuous, otherwise `'v'`(`'h'`) if only `x`(`y`) is + provided) + color_discrete_sequence : list of str + Strings should define valid CSS-colors. When `color` is set and the + values in the corresponding column are not numeric, values in that + column are assigned colors by cycling through `color_discrete_sequence` + in the order described in `category_orders`, unless the value of + `color` is a key in `color_discrete_map`. Various useful color + sequences are available in the `plotly.express.colors` submodules, + specifically `plotly.express.colors.qualitative`. + color_discrete_map : dict with str keys and str values (default `{}`) + String values should define valid CSS-colors Used to override + `color_discrete_sequence` to assign a specific colors to marks + corresponding with specific values. Keys in `color_discrete_map` should + be values in the column denoted by `color`. Alternatively, if the + values of `color` are valid colors, the string `'identity'` may be + passed to cause them to be used directly. + marginal_x : str + One of `'rug'`, `'box'`, `'violin'`, or `'histogram'`. If set, a + horizontal subplot is drawn above the main plot, visualizing the + x-distribution. + marginal_y : str + One of `'rug'`, `'box'`, `'violin'`, or `'histogram'`. If set, a + vertical subplot is drawn to the right of the main plot, visualizing + the y-distribution. + trendline : str + One of `'ols'`, `'lowess'`, `'rolling'`, `'expanding'` or `'ewm'`. If + `'ols'`, an Ordinary Least Squares regression line will be drawn for + each discrete-color/symbol group. If `'lowess`', a Locally Weighted + Scatterplot Smoothing line will be drawn for each discrete-color/symbol + group. If `'rolling`', a Rolling (e.g. rolling average, rolling median) + line will be drawn for each discrete-color/symbol group. If + `'expanding`', an Expanding (e.g. expanding average, expanding sum) + line will be drawn for each discrete-color/symbol group. If `'ewm`', an + Exponentially Weighted Moment (e.g. exponentially-weighted moving + average) line will be drawn for each discrete-color/symbol group. See + the docstrings for the functions in + `plotly.express.trendline_functions` for more details on these + functions and how to configure them with the `trendline_options` + argument. + trendline_options : dict + Options passed as the first argument to the function from + `plotly.express.trendline_functions` named in the `trendline` + argument. + trendline_color_override : str + Valid CSS color. If provided, and if `trendline` is set, all trendlines + will be drawn in this color rather than in the same color as the traces + from which they draw their inputs. + trendline_scope : str (one of `'trace'` or `'overall'`, default `'trace'`) + If `'trace'`, then one trendline is drawn per trace (i.e. per color, + symbol, facet, animation frame etc) and if `'overall'` then one + trendline is computed for the entire dataset, and replicated across all + facets. + log_x : boolean (default `False`) + If `True`, the x-axis is log-scaled in cartesian coordinates. + log_y : boolean (default `False`) + If `True`, the y-axis is log-scaled in cartesian coordinates. + range_x : list of two numbers + If provided, overrides auto-scaling on the x-axis in cartesian + coordinates. + range_y : list of two numbers + If provided, overrides auto-scaling on the y-axis in cartesian + coordinates. + histfunc : str (default `'count'` if no arguments are provided, else `'sum'`) + One of `'count'`, `'sum'`, `'avg'`, `'min'`, or `'max'`. Function used + to aggregate values for summarization (note: can be normalized with + `histnorm`). The arguments to this function are the values of `z`. + histnorm : str (default `None`) + One of `'percent'`, `'probability'`, `'density'`, or `'probability + density'` If `None`, the output of `histfunc` is used as is. If + `'probability'`, the output of `histfunc` for a given bin is divided by + the sum of the output of `histfunc` for all bins. If `'percent'`, the + output of `histfunc` for a given bin is divided by the sum of the + output of `histfunc` for all bins and multiplied by 100. If + `'density'`, the output of `histfunc` for a given bin is divided by the + size of the bin. If `'probability density'`, the output of `histfunc` + for a given bin is normalized such that it corresponds to the + probability that a random event whose distribution is described by the + output of `histfunc` will fall into that bin. + nbinsx : int + Positive integer. Sets the number of bins along the x axis. + nbinsy : int + Positive integer. Sets the number of bins along the y axis. + text_auto : bool or string (default `False`) + If `True` or a string, the x or y or z values will be displayed as + text, depending on the orientation A string like `'.2f'` will be + interpreted as a `texttemplate` numeric formatting directive. + title : str + The figure title. + template : str or dict or plotly.graph_objects.layout.Template instance + The figure template name (must be a key in plotly.io.templates) or + definition. + width : int (default `None`) + The figure width in pixels. + height : int (default `None`) + The figure height in pixels. + + Returns + -------- + plotly.graph_objects.Figure """ return make_figure( args=locals(), @@ -133,19 +554,6 @@ def density_contour( ) -density_contour.__doc__ = make_docstring( - density_contour, - append_dict=dict( - x=_wide_mode_xy_append, - y=_wide_mode_xy_append, - z=[ - "For `density_heatmap` and `density_contour` these values are used as the inputs to `histfunc`.", - ], - histfunc=["The arguments to this function are the values of `z`."], - ), -) - - def density_heatmap( data_frame=None, x=None, @@ -188,6 +596,165 @@ def density_heatmap( In a density heatmap, rows of `data_frame` are grouped together into colored rectangular tiles to visualize the 2D distribution of an aggregate function `histfunc` (e.g. the count or sum) of the value `z`. + + Parameters + ---------- + data_frame : DataFrame or array-like or dict + This argument needs to be passed for column names (and not keyword + names) to be used. Array-like and dict are transformed internally to a + pandas DataFrame. Optional: if missing, a DataFrame gets constructed + under the hood using the other arguments. + x : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + position marks along the x axis in cartesian coordinates. Either `x` or + `y` can optionally be a list of column references or array_likes, in + which case the data will be treated as if it were 'wide' rather than + 'long'. + y : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + position marks along the y axis in cartesian coordinates. Either `x` or + `y` can optionally be a list of column references or array_likes, in + which case the data will be treated as if it were 'wide' rather than + 'long'. + z : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + position marks along the z axis in cartesian coordinates. For + `density_heatmap` and `density_contour` these values are used as the + inputs to `histfunc`. + facet_row : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign marks to facetted subplots in the vertical direction. + facet_col : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign marks to facetted subplots in the horizontal direction. + facet_col_wrap : int + Maximum number of facet columns. Wraps the column variable at this + width, so that the column facets span multiple rows. Ignored if 0, and + forced to 0 if `facet_row` or a `marginal` is set. + facet_row_spacing : float between 0 and 1 + Spacing between facet rows, in paper units. Default is 0.03 or 0.07 + when facet_col_wrap is used. + facet_col_spacing : float between 0 and 1 + Spacing between facet columns, in paper units Default is 0.02. + hover_name : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like appear in bold + in the hover tooltip. + hover_data : str, or list of str or int, or Series or array-like, or dict + Either a name or list of names of columns in `data_frame`, or pandas + Series, or array_like objects or a dict with column names as keys, with + values True (for default formatting) False (in order to remove this + column from hover information), or a formatting string, for example + ':.3f' or '|%a' or list-like data to appear in the hover tooltip or + tuples with a bool or formatting string as first element, and list-like + data to appear in hover as second element Values from these columns + appear as extra data in the hover tooltip. + animation_frame : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign marks to animation frames. + animation_group : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + provide object-constancy across animation frames: rows with matching + `animation_group`s will be treated as if they describe the same object + in each frame. + category_orders : dict with str keys and list of str values (default `{}`) + By default, in Python 3.6+, the order of categorical values in axes, + legends and facets depends on the order in which these values are first + encountered in `data_frame` (and no order is guaranteed by default in + Python below 3.6). This parameter is used to force a specific ordering + of values per column. The keys of this dict should correspond to column + names, and the values should be lists of strings corresponding to the + specific display order desired. + labels : dict with str keys and str values (default `{}`) + By default, column names are used in the figure for axis titles, legend + entries and hovers. This parameter allows this to be overridden. The + keys of this dict should correspond to column names, and the values + should correspond to the desired label to be displayed. + orientation : str, one of `'h'` for horizontal or `'v'` for vertical. + (default `'v'` if `x` and `y` are provided and both continuous or both + categorical, otherwise `'v'`(`'h'`) if `x`(`y`) is categorical and + `y`(`x`) is continuous, otherwise `'v'`(`'h'`) if only `x`(`y`) is + provided) + color_continuous_scale : list of str + Strings should define valid CSS-colors This list is used to build a + continuous color scale when the column denoted by `color` contains + numeric data. Various useful color scales are available in the + `plotly.express.colors` submodules, specifically + `plotly.express.colors.sequential`, `plotly.express.colors.diverging` + and `plotly.express.colors.cyclical`. + range_color : list of two numbers + If provided, overrides auto-scaling on the continuous color scale. + color_continuous_midpoint : number (default `None`) + If set, computes the bounds of the continuous color scale to have the + desired midpoint. Setting this value is recommended when using + `plotly.express.colors.diverging` color scales as the inputs to + `color_continuous_scale`. + marginal_x : str + One of `'rug'`, `'box'`, `'violin'`, or `'histogram'`. If set, a + horizontal subplot is drawn above the main plot, visualizing the + x-distribution. + marginal_y : str + One of `'rug'`, `'box'`, `'violin'`, or `'histogram'`. If set, a + vertical subplot is drawn to the right of the main plot, visualizing + the y-distribution. + opacity : float + Value between 0 and 1. Sets the opacity for markers. + log_x : boolean (default `False`) + If `True`, the x-axis is log-scaled in cartesian coordinates. + log_y : boolean (default `False`) + If `True`, the y-axis is log-scaled in cartesian coordinates. + range_x : list of two numbers + If provided, overrides auto-scaling on the x-axis in cartesian + coordinates. + range_y : list of two numbers + If provided, overrides auto-scaling on the y-axis in cartesian + coordinates. + histfunc : str (default `'count'` if no arguments are provided, else `'sum'`) + One of `'count'`, `'sum'`, `'avg'`, `'min'`, or `'max'`. Function used + to aggregate values for summarization (note: can be normalized with + `histnorm`). The arguments to this function are the values of `z`. + histnorm: str (default `None`) + One of `'percent'`, `'probability'`, `'density'`, or `'probability + density'` If `None`, the output of `histfunc` is used as is. If + `'probability'`, the output of `histfunc` for a given bin is divided by + the sum of the output of `histfunc` for all bins. If `'percent'`, the + output of `histfunc` for a given bin is divided by the sum of the + output of `histfunc` for all bins and multiplied by 100. If + `'density'`, the output of `histfunc` for a given bin is divided by the + size of the bin. If `'probability density'`, the output of `histfunc` + for a given bin is normalized such that it corresponds to the + probability that a random event whose distribution is described by the + output of `histfunc` will fall into that bin. + nbinsx : int + Positive integer. Sets the number of bins along the x axis. + nbinsy : int + Positive integer. Sets the number of bins along the y axis. + text_auto : bool or string (default `False`) + If `True` or a string, the x or y or z values will be displayed as + text, depending on the orientation A string like `'.2f'` will be + interpreted as a `texttemplate` numeric formatting directive. + title : str + The figure title. + subtitle : str + The figure subtitle. + template : str or dict or plotly.graph_objects.layout.Template instance + The figure template name (must be a key in plotly.io.templates) or + definition. + width : int (default `None`) + The figure width in pixels. + height : int (default `None`) + The figure height in pixels. + + Returns + ------- + plotly.graph_objects.Figure """ return make_figure( args=locals(), @@ -203,21 +770,6 @@ def density_heatmap( ) -density_heatmap.__doc__ = make_docstring( - density_heatmap, - append_dict=dict( - x=_wide_mode_xy_append, - y=_wide_mode_xy_append, - z=[ - "For `density_heatmap` and `density_contour` these values are used as the inputs to `histfunc`.", - ], - histfunc=[ - "The arguments to this function are the values of `z`.", - ], - ), -) - - def line( data_frame=None, x=None, @@ -266,13 +818,214 @@ def line( """ In a 2D line plot, each row of `data_frame` is represented as a vertex of a polyline mark in 2D space. + + Parameters + ---------- + data_frame : DataFrame or array-like or dict + This argument needs to be passed for column names (and not keyword + names) to be used. Array-like and dict are transformed internally to a + pandas DataFrame. Optional: if missing, a DataFrame gets constructed + under the hood using the other arguments. + x : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + position marks along the x axis in cartesian coordinates. Either `x` or + `y` can optionally be a list of column references or array_likes, in + which case the data will be treated as if it were 'wide' rather than + 'long'. + y : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + position marks along the y axis in cartesian coordinates. Either `x` or + `y` can optionally be a list of column references or array_likes, in + which case the data will be treated as if it were 'wide' rather than + 'long'. + line_group : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + group rows of `data_frame` into lines. + color : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign color to marks. + line_dash : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign dash-patterns to lines. + symbol : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign symbols to marks. + hover_name : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like appear in bold + in the hover tooltip. + hover_data : str, or list of str or int, or Series or array-like, or dict + Either a name or list of names of columns in `data_frame`, or pandas + Series, or array_like objects or a dict with column names as keys, with + values True (for default formatting) False (in order to remove this + column from hover information), or a formatting string, for example + ':.3f' or '|%a' or list-like data to appear in the hover tooltip or + tuples with a bool or formatting string as first element, and list-like + data to appear in hover as second element Values from these columns + appear as extra data in the hover tooltip. + custom_data : str, or list of str or int, or Series or array-like + Either name or list of names of columns in `data_frame`, or pandas + Series, or array_like objects Values from these columns are extra data, + to be used in widgets or Dash callbacks for example. This data is not + user-visible but is included in events emitted by the figure (lasso + selection etc.) + text : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like appear in the + figure as text labels. + facet_row : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign marks to facetted subplots in the vertical direction. + facet_col : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign marks to facetted subplots in the horizontal direction. + facet_col_wrap : int + Maximum number of facet columns. Wraps the column variable at this + width, so that the column facets span multiple rows. Ignored if 0, and + forced to 0 if `facet_row` or a `marginal` is set. + facet_row_spacing : float between 0 and 1 + Spacing between facet rows, in paper units. Default is 0.03 or 0.07 + when facet_col_wrap is used. + facet_col_spacing : float between 0 and 1 + Spacing between facet columns, in paper units Default is 0.02. + error_x : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + size x-axis error bars. If `error_x_minus` is `None`, error bars will + be symmetrical, otherwise `error_x` is used for the positive direction + only. + error_x_minus : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + size x-axis error bars in the negative direction. Ignored if `error_x` + is `None`. + error_y : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + size y-axis error bars. If `error_y_minus` is `None`, error bars will + be symmetrical, otherwise `error_y` is used for the positive direction + only. + error_y_minus : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + size y-axis error bars in the negative direction. Ignored if `error_y` + is `None`. + animation_frame : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign marks to animation frames. + animation_group : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + provide object-constancy across animation frames: rows with matching + `animation_group`s will be treated as if they describe the same object + in each frame. + category_orders : dict with str keys and list of str values (default `{}`) + By default, in Python 3.6+, the order of categorical values in axes, + legends and facets depends on the order in which these values are first + encountered in `data_frame` (and no order is guaranteed by default in + Python below 3.6). This parameter is used to force a specific ordering + of values per column. The keys of this dict should correspond to column + names, and the values should be lists of strings corresponding to the + specific display order desired. + labels : dict with str keys and str values (default `{}`) + By default, column names are used in the figure for axis titles, legend + entries and hovers. This parameter allows this to be overridden. The + keys of this dict should correspond to column names, and the values + should correspond to the desired label to be displayed. + orientation : str, one of `'h'` for horizontal or `'v'` for vertical. + (default `'v'` if `x` and `y` are provided and both continuous or both + categorical, otherwise `'v'`(`'h'`) if `x`(`y`) is categorical and + `y`(`x`) is continuous, otherwise `'v'`(`'h'`) if only `x`(`y`) is + provided) + color_discrete_sequence : list of str + Strings should define valid CSS-colors. When `color` is set and the + values in the corresponding column are not numeric, values in that + column are assigned colors by cycling through `color_discrete_sequence` + in the order described in `category_orders`, unless the value of + `color` is a key in `color_discrete_map`. Various useful color + sequences are available in the `plotly.express.colors` submodules, + specifically `plotly.express.colors.qualitative`. + color_discrete_map : dict with str keys and str values (default `{}`) + String values should define valid CSS-colors Used to override + `color_discrete_sequence` to assign a specific colors to marks + corresponding with specific values. Keys in `color_discrete_map` should + be values in the column denoted by `color`. Alternatively, if the + values of `color` are valid colors, the string `'identity'` may be + passed to cause them to be used directly. + line_dash_sequence : list of str + Strings should define valid plotly.js dash-patterns. When `line_dash` + is set, values in that column are assigned dash-patterns by cycling + through `line_dash_sequence` in the order described in + `category_orders`, unless the value of `line_dash` is a key in + `line_dash_map`. + line_dash_map : dict with str keys and str values (default `{}`) + Strings values define plotly.js dash-patterns. Used to override + `line_dash_sequences` to assign a specific dash-patterns to lines + corresponding with specific values. Keys in `line_dash_map` should be + values in the column denoted by `line_dash`. Alternatively, if the + values of `line_dash` are valid line-dash names, the string + `'identity'` may be passed to cause them to be used directly. + symbol_sequence : list of str + Strings should define valid plotly.js symbols. When `symbol` is set, + values in that column are assigned symbols by cycling through + `symbol_sequence` in the order described in `category_orders`, unless + the value of `symbol` is a key in `symbol_map`. + symbol_map : dict with str keys and str values (default `{}`) + String values should define plotly.js symbols Used to override + `symbol_sequence` to assign a specific symbols to marks corresponding + with specific values. Keys in `symbol_map` should be values in the + column denoted by `symbol`. Alternatively, if the values of `symbol` + are valid symbol names, the string `'identity'` may be passed to cause + them to be used directly. + markers : boolean (default `False`) + If `True`, markers are shown on lines. + log_x : boolean (default `False`) + If `True`, the x-axis is log-scaled in cartesian coordinates. + log_y : boolean (default `False`) + If `True`, the y-axis is log-scaled in cartesian coordinates. + range_x : list of two numbers + If provided, overrides auto-scaling on the x-axis in cartesian + coordinates. + range_y : list of two numbers + If provided, overrides auto-scaling on the y-axis in cartesian + coordinates. + line_shape : str (default `'linear'`) + One of `'linear'`, `'spline'`, `'hv'`, `'vh'`, `'hvh'`, or `'vhv'` + render_mode : str + One of `'auto'`, `'svg'` or `'webgl'`, default `'auto'` Controls the + browser API used to draw marks. `'svg'` is appropriate for figures of + less than 1000 data points, and will allow for fully-vectorized output. + `'webgl'` is likely necessary for acceptable performance above 1000 + points but rasterizes part of the output. `'auto'` uses heuristics to + choose the mode. + title : str + The figure title. + subtitle : str + The figure subtitle. + template : str or dict or plotly.graph_objects.layout.Template instance + The figure template name (must be a key in plotly.io.templates) or + definition. + width : int (default `None`) + The figure width in pixels. + height : int (default `None`) + The figure height in pixels. + + Returns + ------- + plotly.graph_objects.Figure """ return make_figure(args=locals(), constructor=go.Scatter) -line.__doc__ = make_docstring(line, append_dict=_cartesian_append_dict) - - def area( data_frame=None, x=None, @@ -318,6 +1071,186 @@ def area( In a stacked area plot, each row of `data_frame` is represented as a vertex of a polyline mark in 2D space. The area between successive polylines is filled. + + Parameters + ---------- + data_frame : DataFrame or array-like or dict + This argument needs to be passed for column names (and not keyword + names) to be used. Array-like and dict are transformed internally to a + pandas DataFrame. Optional: if missing, a DataFrame gets constructed + under the hood using the other arguments. + x : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + position marks along the x axis in cartesian coordinates. Either `x` or + `y` can optionally be a list of column references or array_likes, in + which case the data will be treated as if it were 'wide' rather than + 'long'. + y : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + position marks along the y axis in cartesian coordinates. Either `x` or + `y` can optionally be a list of column references or array_likes, in + which case the data will be treated as if it were 'wide' rather than + 'long'. + line_group : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + group rows of `data_frame` into lines. + color : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign color to marks. + pattern_shape : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign pattern shapes to marks. + symbol : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign symbols to marks. + hover_name : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like appear in bold + in the hover tooltip. + hover_data : str, or list of str or int, or Series or array-like, or dict + Either a name or list of names of columns in `data_frame`, or pandas + Series, or array_like objects or a dict with column names as keys, with + values True (for default formatting) False (in order to remove this + column from hover information), or a formatting string, for example + ':.3f' or '|%a' or list-like data to appear in the hover tooltip or + tuples with a bool or formatting string as first element, and list-like + data to appear in hover as second element Values from these columns + appear as extra data in the hover tooltip. + custom_data : str, or list of str or int, or Series or array-like + Either name or list of names of columns in `data_frame`, or pandas + Series, or array_like objects Values from these columns are extra data, + to be used in widgets or Dash callbacks for example. This data is not + user-visible but is included in events emitted by the figure (lasso + selection etc.) + text : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like appear in the + figure as text labels. + facet_row : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign marks to facetted subplots in the vertical direction. + facet_col : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign marks to facetted subplots in the horizontal direction. + facet_col_wrap : int + Maximum number of facet columns. Wraps the column variable at this + width, so that the column facets span multiple rows. Ignored if 0, and + forced to 0 if `facet_row` or a `marginal` is set. + facet_row_spacing : float between 0 and 1 + Spacing between facet rows, in paper units. Default is 0.03 or 0.07 + when facet_col_wrap is used. + facet_col_spacing : float between 0 and 1 + Spacing between facet columns, in paper units Default is 0.02. + animation_frame : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign marks to animation frames. + animation_group : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + provide object-constancy across animation frames: rows with matching + `animation_group`s will be treated as if they describe the same object + in each frame. + category_orders : dict with str keys and list of str values (default `{}`) + By default, in Python 3.6+, the order of categorical values in axes, + legends and facets depends on the order in which these values are first + encountered in `data_frame` (and no order is guaranteed by default in + Python below 3.6). This parameter is used to force a specific ordering + of values per column. The keys of this dict should correspond to column + names, and the values should be lists of strings corresponding to the + specific display order desired. + labels : dict with str keys and str values (default `{}`) + By default, column names are used in the figure for axis titles, legend + entries and hovers. This parameter allows this to be overridden. The + keys of this dict should correspond to column names, and the values + should correspond to the desired label to be displayed. + color_discrete_sequence : list of str + Strings should define valid CSS-colors. When `color` is set and the + values in the corresponding column are not numeric, values in that + column are assigned colors by cycling through `color_discrete_sequence` + in the order described in `category_orders`, unless the value of + `color` is a key in `color_discrete_map`. Various useful color + sequences are available in the `plotly.express.colors` submodules, + specifically `plotly.express.colors.qualitative`. + color_discrete_map : dict with str keys and str values (default `{}`) + String values should define valid CSS-colors Used to override + `color_discrete_sequence` to assign a specific colors to marks + corresponding with specific values. Keys in `color_discrete_map` should + be values in the column denoted by `color`. Alternatively, if the + values of `color` are valid colors, the string `'identity'` may be + passed to cause them to be used directly. + pattern_shape_sequence : list of str + Strings should define valid plotly.js patterns-shapes. When + `pattern_shape` is set, values in that column are assigned patterns- + shapes by cycling through `pattern_shape_sequence` in the order + described in `category_orders`, unless the value of `pattern_shape` is + a key in `pattern_shape_map`. + pattern_shape_map : dict with str keys and str values (default `{}`) + Strings values define plotly.js patterns-shapes. Used to override + `pattern_shape_sequences` to assign a specific patterns-shapes to lines + corresponding with specific values. Keys in `pattern_shape_map` should + be values in the column denoted by `pattern_shape`. Alternatively, if + the values of `pattern_shape` are valid patterns-shapes names, the + string `'identity'` may be passed to cause them to be used directly. + symbol_sequence : list of str + Strings should define valid plotly.js symbols. When `symbol` is set, + values in that column are assigned symbols by cycling through + `symbol_sequence` in the order described in `category_orders`, unless + the value of `symbol` is a key in `symbol_map`. + symbol_map : dict with str keys and str values (default `{}`) + String values should define plotly.js symbols Used to override + `symbol_sequence` to assign a specific symbols to marks corresponding + with specific values. Keys in `symbol_map` should be values in the + column denoted by `symbol`. Alternatively, if the values of `symbol` + are valid symbol names, the string `'identity'` may be passed to cause + them to be used directly. + markers : boolean (default `False`) + If `True`, markers are shown on lines. + orientation : str, one of `'h'` for horizontal or `'v'` for vertical. + (default `'v'` if `x` and `y` are provided and both continuous or both + categorical, otherwise `'v'`(`'h'`) if `x`(`y`) is categorical and + `y`(`x`) is continuous, otherwise `'v'`(`'h'`) if only `x`(`y`) is + provided) + groupnorm : str (default `None`) + One of `'fraction'` or `'percent'`. If `'fraction'`, the value of each + point is divided by the sum of all values at that location coordinate. + `'percent'` is the same but multiplied by 100 to show percentages. + `None` will stack up all values at each location coordinate. + log_x : boolean (default `False`) + If `True`, the x-axis is log-scaled in cartesian coordinates. + log_y : boolean (default `False`) + If `True`, the y-axis is log-scaled in cartesian coordinates. + range_x : list of two numbers + If provided, overrides auto-scaling on the x-axis in cartesian + coordinates. + range_y : list of two numbers + If provided, overrides auto-scaling on the y-axis in cartesian + coordinates. + line_shape : str (default `'linear'`) + One of `'linear'`, `'spline'`, `'hv'`, `'vh'`, `'hvh'`, or `'vhv'` + title : str + The figure title. + subtitle : str + The figure subtitle. + template : str or dict or plotly.graph_objects.layout.Template instance + The figure template name (must be a key in plotly.io.templates) or + definition. + width : int (default `None`) + The figure width in pixels. + height : int (default `None`) + The figure height in pixels. + + Returns + ------- + plotly.graph_objects.Figure """ return make_figure( args=locals(), @@ -326,9 +1259,6 @@ def area( ) -area.__doc__ = make_docstring(area, append_dict=_cartesian_append_dict) - - def bar( data_frame=None, x=None, @@ -377,6 +1307,208 @@ def bar( """ In a bar plot, each row of `data_frame` is represented as a rectangular mark. + + Parameters + ---------- + data_frame : DataFrame or array-like or dict + This argument needs to be passed for column names (and not keyword + names) to be used. Array-like and dict are transformed internally to a + pandas DataFrame. Optional: if missing, a DataFrame gets constructed + under the hood using the other arguments. + x : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + position marks along the x axis in cartesian coordinates. Either `x` or + `y` can optionally be a list of column references or array_likes, in + which case the data will be treated as if it were 'wide' rather than + 'long'. + y : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + position marks along the y axis in cartesian coordinates. Either `x` or + `y` can optionally be a list of column references or array_likes, in + which case the data will be treated as if it were 'wide' rather than + 'long'. + color : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign color to marks. + pattern_shape : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign pattern shapes to marks. + facet_row : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign marks to facetted subplots in the vertical direction. + facet_col : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign marks to facetted subplots in the horizontal direction. + facet_col_wrap : int + Maximum number of facet columns. Wraps the column variable at this + width, so that the column facets span multiple rows. Ignored if 0, and + forced to 0 if `facet_row` or a `marginal` is set. + facet_row_spacing : float between 0 and 1 + Spacing between facet rows, in paper units. Default is 0.03 or 0.07 + when facet_col_wrap is used. + facet_col_spacing : float between 0 and 1 + Spacing between facet columns, in paper units Default is 0.02. + hover_name : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like appear in bold + in the hover tooltip. + hover_data : str, or list of str or int, or Series or array-like, or dict + Either a name or list of names of columns in `data_frame`, or pandas + Series, or array_like objects or a dict with column names as keys, with + values True (for default formatting) False (in order to remove this + column from hover information), or a formatting string, for example + ':.3f' or '|%a' or list-like data to appear in the hover tooltip or + tuples with a bool or formatting string as first element, and list-like + data to appear in hover as second element Values from these columns + appear as extra data in the hover tooltip. + custom_data : str, or list of str or int, or Series or array-like + Either name or list of names of columns in `data_frame`, or pandas + Series, or array_like objects Values from these columns are extra data, + to be used in widgets or Dash callbacks for example. This data is not + user-visible but is included in events emitted by the figure (lasso + selection etc.) + text : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like appear in the + figure as text labels. + base : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + position the base of the bar. + error_x : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + size x-axis error bars. If `error_x_minus` is `None`, error bars will + be symmetrical, otherwise `error_x` is used for the positive direction + only. + error_x_minus : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + size x-axis error bars in the negative direction. Ignored if `error_x` + is `None`. + error_y : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + size y-axis error bars. If `error_y_minus` is `None`, error bars will + be symmetrical, otherwise `error_y` is used for the positive direction + only. + error_y_minus : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + size y-axis error bars in the negative direction. Ignored if `error_y` + is `None`. + animation_frame : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign marks to animation frames. + animation_group : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + provide object-constancy across animation frames: rows with matching + `animation_group`s will be treated as if they describe the same object + in each frame. + category_orders : dict with str keys and list of str values (default `{}`) + By default, in Python 3.6+, the order of categorical values in axes, + legends and facets depends on the order in which these values are first + encountered in `data_frame` (and no order is guaranteed by default in + Python below 3.6). This parameter is used to force a specific ordering + of values per column. The keys of this dict should correspond to column + names, and the values should be lists of strings corresponding to the + specific display order desired. + labels : dict with str keys and str values (default `{}`) + By default, column names are used in the figure for axis titles, legend + entries and hovers. This parameter allows this to be overridden. The + keys of this dict should correspond to column names, and the values + should correspond to the desired label to be displayed. + color_discrete_sequence : list of str + Strings should define valid CSS-colors. When `color` is set and the + values in the corresponding column are not numeric, values in that + column are assigned colors by cycling through `color_discrete_sequence` + in the order described in `category_orders`, unless the value of + `color` is a key in `color_discrete_map`. Various useful color + sequences are available in the `plotly.express.colors` submodules, + specifically `plotly.express.colors.qualitative`. + color_discrete_map : dict with str keys and str values (default `{}`) + String values should define valid CSS-colors Used to override + `color_discrete_sequence` to assign a specific colors to marks + corresponding with specific values. Keys in `color_discrete_map` should + be values in the column denoted by `color`. Alternatively, if the + values of `color` are valid colors, the string `'identity'` may be + passed to cause them to be used directly. + color_continuous_scale : list of str + Strings should define valid CSS-colors This list is used to build a + continuous color scale when the column denoted by `color` contains + numeric data. Various useful color scales are available in the + `plotly.express.colors` submodules, specifically + `plotly.express.colors.sequential`, `plotly.express.colors.diverging` + and `plotly.express.colors.cyclical`. + pattern_shape_sequence : list of str + Strings should define valid plotly.js patterns-shapes. When + `pattern_shape` is set, values in that column are assigned patterns- + shapes by cycling through `pattern_shape_sequence` in the order + described in `category_orders`, unless the value of `pattern_shape` is + a key in `pattern_shape_map`. + pattern_shape_map : dict with str keys and str values (default `{}`) + Strings values define plotly.js patterns-shapes. Used to override + `pattern_shape_sequences` to assign a specific patterns-shapes to lines + corresponding with specific values. Keys in `pattern_shape_map` should + be values in the column denoted by `pattern_shape`. Alternatively, if + the values of `pattern_shape` are valid patterns-shapes names, the + string `'identity'` may be passed to cause them to be used directly. + range_color : list of two numbers + If provided, overrides auto-scaling on the continuous color scale. + color_continuous_midpoint : number (default `None`) + If set, computes the bounds of the continuous color scale to have the + desired midpoint. Setting this value is recommended when using + `plotly.express.colors.diverging` color scales as the inputs to + `color_continuous_scale`. + opacity : float + Value between 0 and 1. Sets the opacity for markers. + orientation : str, one of `'h'` for horizontal or `'v'` for vertical. + (default `'v'` if `x` and `y` are provided and both continuous or both + categorical, otherwise `'v'`(`'h'`) if `x`(`y`) is categorical and + `y`(`x`) is continuous, otherwise `'v'`(`'h'`) if only `x`(`y`) is + provided) + barmode : str (default `'relative'`) + One of `'group'`, `'overlay'` or `'relative'` In `'relative'` mode, + bars are stacked above zero for positive values and below zero for + negative values. In `'overlay'` mode, bars are drawn on top of one + another. In `'group'` mode, bars are placed beside each other. + log_x : boolean (default `False`) + If `True`, the x-axis is log-scaled in cartesian coordinates. + log_y : boolean (default `False`) + If `True`, the y-axis is log-scaled in cartesian coordinates. + range_x : list of two numbers + If provided, overrides auto-scaling on the x-axis in cartesian + coordinates. + range_y : list of two numbers + If provided, overrides auto-scaling on the y-axis in cartesian + coordinates. + text_auto : bool or string (default `False`) + If `True` or a string, the x or y or z values will be displayed as + text, depending on the orientation A string like `'.2f'` will be + interpreted as a `texttemplate` numeric formatting directive. + title : str + The figure title. + subtitle : str + The figure subtitle. + template : str or dict or plotly.graph_objects.layout.Template instance + The figure template name (must be a key in plotly.io.templates) or + definition. + width : int (default `None`) + The figure width in pixels. + height : int (default `None`) + The figure height in pixels. + + Returns + ------- + plotly.graph_objects.Figure """ return make_figure( args=locals(), @@ -386,9 +1518,6 @@ def bar( ) -bar.__doc__ = make_docstring(bar, append_dict=_cartesian_append_dict) - - def timeline( data_frame=None, x_start=None, @@ -428,6 +1557,162 @@ def timeline( """ In a timeline plot, each row of `data_frame` is represented as a rectangular mark on an x axis of type `date`, spanning from `x_start` to `x_end`. + + Parameters + ---------- + data_frame : DataFrame or array-like or dict + This argument needs to be passed for column names (and not keyword + names) to be used. Array-like and dict are transformed internally to a + pandas DataFrame. Optional: if missing, a DataFrame gets constructed + under the hood using the other arguments. + x_start : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. (required) Values from this column or array_like are + used to position marks along the x axis in cartesian coordinates. + x_end : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. (required) Values from this column or array_like are + used to position marks along the x axis in cartesian coordinates. + y : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + position marks along the y axis in cartesian coordinates. + color : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign color to marks. + pattern_shape : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign pattern shapes to marks. + facet_row : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign marks to facetted subplots in the vertical direction. + facet_col : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign marks to facetted subplots in the horizontal direction. + facet_col_wrap : int + Maximum number of facet columns. Wraps the column variable at this + width, so that the column facets span multiple rows. Ignored if 0, and + forced to 0 if `facet_row` or a `marginal` is set. + facet_row_spacing : float between 0 and 1 + Spacing between facet rows, in paper units. Default is 0.03 or 0.07 + when facet_col_wrap is used. + facet_col_spacing : float between 0 and 1 + Spacing between facet columns, in paper units Default is 0.02. + hover_name : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like appear in bold + in the hover tooltip. + hover_data : str, or list of str or int, or Series or array-like, or dict + Either a name or list of names of columns in `data_frame`, or pandas + Series, or array_like objects or a dict with column names as keys, with + values True (for default formatting) False (in order to remove this + column from hover information), or a formatting string, for example + ':.3f' or '|%a' or list-like data to appear in the hover tooltip or + tuples with a bool or formatting string as first element, and list-like + data to appear in hover as second element Values from these columns + appear as extra data in the hover tooltip. + custom_data : str, or list of str or int, or Series or array-like + Either name or list of names of columns in `data_frame`, or pandas + Series, or array_like objects Values from these columns are extra data, + to be used in widgets or Dash callbacks for example. This data is not + user-visible but is included in events emitted by the figure (lasso + selection etc.) + text : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like appear in the + figure as text labels. + animation_frame : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign marks to animation frames. + animation_group : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + provide object-constancy across animation frames: rows with matching + `animation_group`s will be treated as if they describe the same object + in each frame. + category_orders : dict with str keys and list of str values (default `{}`) + By default, in Python 3.6+, the order of categorical values in axes, + legends and facets depends on the order in which these values are first + encountered in `data_frame` (and no order is guaranteed by default in + Python below 3.6). This parameter is used to force a specific ordering + of values per column. The keys of this dict should correspond to column + names, and the values should be lists of strings corresponding to the + specific display order desired. + labels : dict with str keys and str values (default `{}`) + By default, column names are used in the figure for axis titles, legend + entries and hovers. This parameter allows this to be overridden. The + keys of this dict should correspond to column names, and the values + should correspond to the desired label to be displayed. + color_discrete_sequence : list of str + Strings should define valid CSS-colors. When `color` is set and the + values in the corresponding column are not numeric, values in that + column are assigned colors by cycling through `color_discrete_sequence` + in the order described in `category_orders`, unless the value of + `color` is a key in `color_discrete_map`. Various useful color + sequences are available in the `plotly.express.colors` submodules, + specifically `plotly.express.colors.qualitative`. + color_discrete_map : dict with str keys and str values (default `{}`) + String values should define valid CSS-colors Used to override + `color_discrete_sequence` to assign a specific colors to marks + corresponding with specific values. Keys in `color_discrete_map` should + be values in the column denoted by `color`. Alternatively, if the + values of `color` are valid colors, the string `'identity'` may be + passed to cause them to be used directly. + pattern_shape_sequence : list of str + Strings should define valid plotly.js patterns-shapes. When + `pattern_shape` is set, values in that column are assigned patterns- + shapes by cycling through `pattern_shape_sequence` in the order + described in `category_orders`, unless the value of `pattern_shape` is + a key in `pattern_shape_map`. + pattern_shape_map : dict with str keys and str values (default `{}`) + Strings values define plotly.js patterns-shapes. Used to override + `pattern_shape_sequences` to assign a specific patterns-shapes to lines + corresponding with specific values. Keys in `pattern_shape_map` should + be values in the column denoted by `pattern_shape`. Alternatively, if + the values of `pattern_shape` are valid patterns-shapes names, the + string `'identity'` may be passed to cause them to be used directly. + color_continuous_scale : list of str + Strings should define valid CSS-colors This list is used to build a + continuous color scale when the column denoted by `color` contains + numeric data. Various useful color scales are available in the + `plotly.express.colors` submodules, specifically + `plotly.express.colors.sequential`, `plotly.express.colors.diverging` + and `plotly.express.colors.cyclical`. + range_color : list of two numbers + If provided, overrides auto-scaling on the continuous color scale. + color_continuous_midpoint : number (default `None`) + If set, computes the bounds of the continuous color scale to have the + desired midpoint. Setting this value is recommended when using + `plotly.express.colors.diverging` color scales as the inputs to + `color_continuous_scale`. + opacity : float + Value between 0 and 1. Sets the opacity for markers. + range_x : list of two numbers + If provided, overrides auto-scaling on the x-axis in cartesian + coordinates. + range_y : list of two numbers + If provided, overrides auto-scaling on the y-axis in cartesian + coordinates. + title : str + The figure title. + subtitle : str + The figure subtitle. + template : str or dict or plotly.graph_objects.layout.Template instance + The figure template name (must be a key in plotly.io.templates) or + definition. + width : int (default `None`) + The figure width in pixels. + height : int (default `None`) + The figure height in pixels. + + Returns + ------- + plotly.graph_objects.Figure """ return make_figure( args=locals(), @@ -437,9 +1722,6 @@ def timeline( ) -timeline.__doc__ = make_docstring(timeline) - - def histogram( data_frame=None, x=None, @@ -486,6 +1768,189 @@ def histogram( rectangular mark to visualize the 1D distribution of an aggregate function `histfunc` (e.g. the count or sum) of the value `y` (or `x` if `orientation` is `'h'`). + + Parameters + ---------- + data_frame : DataFrame or array-like or dict + This argument needs to be passed for column names (and not keyword + names) to be used. Array-like and dict are transformed internally to a + pandas DataFrame. Optional: if missing, a DataFrame gets constructed + under the hood using the other arguments. + x : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + position marks along the x axis in cartesian coordinates. If + `orientation` is `'h'`, these values are used as inputs to `histfunc`. + Either `x` or `y` can optionally be a list of column references or + array_likes, in which case the data will be treated as if it were + 'wide' rather than 'long'. + y : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + position marks along the y axis in cartesian coordinates. If + `orientation` is `'v'`, these values are used as inputs to `histfunc`. + Either `x` or `y` can optionally be a list of column references or + array_likes, in which case the data will be treated as if it were + 'wide' rather than 'long'. + color : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign color to marks. + pattern_shape : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign pattern shapes to marks. + facet_row : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign marks to facetted subplots in the vertical direction. + facet_col : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign marks to facetted subplots in the horizontal direction. + facet_col_wrap : int + Maximum number of facet columns. Wraps the column variable at this + width, so that the column facets span multiple rows. Ignored if 0, and + forced to 0 if `facet_row` or a `marginal` is set. + facet_row_spacing : float between 0 and 1 + Spacing between facet rows, in paper units. Default is 0.03 or 0.07 + when facet_col_wrap is used. + facet_col_spacing : float between 0 and 1 + Spacing between facet columns, in paper units Default is 0.02. + hover_name : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like appear in bold + in the hover tooltip. + hover_data : str, or list of str or int, or Series or array-like, or dict + Either a name or list of names of columns in `data_frame`, or pandas + Series, or array_like objects or a dict with column names as keys, with + values True (for default formatting) False (in order to remove this + column from hover information), or a formatting string, for example + ':.3f' or '|%a' or list-like data to appear in the hover tooltip or + tuples with a bool or formatting string as first element, and list-like + data to appear in hover as second element Values from these columns + appear as extra data in the hover tooltip. + animation_frame : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign marks to animation frames. + animation_group : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + provide object-constancy across animation frames: rows with matching + `animation_group`s will be treated as if they describe the same object + in each frame. + category_orders : dict with str keys and list of str values (default `{}`) + By default, in Python 3.6+, the order of categorical values in axes, + legends and facets depends on the order in which these values are first + encountered in `data_frame` (and no order is guaranteed by default in + Python below 3.6). This parameter is used to force a specific ordering + of values per column. The keys of this dict should correspond to column + names, and the values should be lists of strings corresponding to the + specific display order desired. + labels : dict with str keys and str values (default `{}`) + By default, column names are used in the figure for axis titles, legend + entries and hovers. This parameter allows this to be overridden. The + keys of this dict should correspond to column names, and the values + should correspond to the desired label to be displayed. + color_discrete_sequence : list of str + Strings should define valid CSS-colors. When `color` is set and the + values in the corresponding column are not numeric, values in that + column are assigned colors by cycling through `color_discrete_sequence` + in the order described in `category_orders`, unless the value of + `color` is a key in `color_discrete_map`. Various useful color + sequences are available in the `plotly.express.colors` submodules, + specifically `plotly.express.colors.qualitative`. + color_discrete_map : dict with str keys and str values (default `{}`) + String values should define valid CSS-colors Used to override + `color_discrete_sequence` to assign a specific colors to marks + corresponding with specific values. Keys in `color_discrete_map` should + be values in the column denoted by `color`. Alternatively, if the + values of `color` are valid colors, the string `'identity'` may be + passed to cause them to be used directly. + pattern_shape_sequence : list of str + Strings should define valid plotly.js patterns-shapes. When + `pattern_shape` is set, values in that column are assigned patterns- + shapes by cycling through `pattern_shape_sequence` in the order + described in `category_orders`, unless the value of `pattern_shape` is + a key in `pattern_shape_map`. + pattern_shape_map : dict with str keys and str values (default `{}`) + Strings values define plotly.js patterns-shapes. Used to override + `pattern_shape_sequences` to assign a specific patterns-shapes to lines + corresponding with specific values. Keys in `pattern_shape_map` should + be values in the column denoted by `pattern_shape`. Alternatively, if + the values of `pattern_shape` are valid patterns-shapes names, the + string `'identity'` may be passed to cause them to be used directly. + marginal : str + One of `'rug'`, `'box'`, `'violin'`, or `'histogram'`. If set, a + subplot is drawn alongside the main plot, visualizing the distribution. + opacity : float + Value between 0 and 1. Sets the opacity for markers. + orientation : str, one of `'h'` for horizontal or `'v'` for vertical. + (default `'v'` if `x` and `y` are provided and both continuous or both + categorical, otherwise `'v'`(`'h'`) if `x`(`y`) is categorical and + `y`(`x`) is continuous, otherwise `'v'`(`'h'`) if only `x`(`y`) is + provided) + barmode : str (default `'relative'`) + One of `'group'`, `'overlay'` or `'relative'` In `'relative'` mode, + bars are stacked above zero for positive values and below zero for + negative values. In `'overlay'` mode, bars are drawn on top of one + another. In `'group'` mode, bars are placed beside each other. + barnorm : str (default `None`) + One of `'fraction'` or `'percent'`. If `'fraction'`, the value of each + bar is divided by the sum of all values at that location coordinate. + `'percent'` is the same but multiplied by 100 to show percentages. + `None` will stack up all values at each location coordinate. + histnorm: str (default `None`) + One of `'percent'`, `'probability'`, `'density'`, or `'probability + density'` If `None`, the output of `histfunc` is used as is. If + `'probability'`, the output of `histfunc` for a given bin is divided by + the sum of the output of `histfunc` for all bins. If `'percent'`, the + output of `histfunc` for a given bin is divided by the sum of the + output of `histfunc` for all bins and multiplied by 100. If + `'density'`, the output of `histfunc` for a given bin is divided by the + size of the bin. If `'probability density'`, the output of `histfunc` + for a given bin is normalized such that it corresponds to the + probability that a random event whose distribution is described by the + output of `histfunc` will fall into that bin. + log_x : boolean (default `False`) + If `True`, the x-axis is log-scaled in cartesian coordinates. + log_y : boolean (default `False`) + If `True`, the y-axis is log-scaled in cartesian coordinates. + range_x : list of two numbers + If provided, overrides auto-scaling on the x-axis in cartesian + coordinates. + range_y : list of two numbers + If provided, overrides auto-scaling on the y-axis in cartesian + coordinates. + histfunc : str (default `'count'` if no arguments are provided, else `'sum'`) + One of `'count'`, `'sum'`, `'avg'`, `'min'`, or `'max'`. Function used + to aggregate values for summarization (note: can be normalized with + `histnorm`). The arguments to this function are the values of `y` (`x`) + if `orientation` is `'v'` (`'h'`). + cumulative : boolean (default `False`) + If `True`, histogram values are cumulative. + nbins : int + Positive integer. Sets the number of bins. + text_auto : bool or string (default `False`) + If `True` or a string, the x or y or z values will be displayed as + text, depending on the orientation A string like `'.2f'` will be + interpreted as a `texttemplate` numeric formatting directive. + title : str + The figure title. + subtitle : str + The figure subtitle. + template : str or dict or plotly.graph_objects.layout.Template instance + The figure template name (must be a key in plotly.io.templates) or + definition. + width : int (default `None`) + The figure width in pixels. + height : int (default `None`) + The figure height in pixels. + + Returns + ------- + plotly.graph_objects.Figure """ return make_figure( args=locals(), @@ -499,20 +1964,6 @@ def histogram( ) -histogram.__doc__ = make_docstring( - histogram, - append_dict=dict( - x=["If `orientation` is `'h'`, these values are used as inputs to `histfunc`."] - + _wide_mode_xy_append, - y=["If `orientation` is `'v'`, these values are used as inputs to `histfunc`."] - + _wide_mode_xy_append, - histfunc=[ - "The arguments to this function are the values of `y` (`x`) if `orientation` is `'v'` (`'h'`).", - ], - ), -) - - def ecdf( data_frame=None, x=None, @@ -561,25 +2012,201 @@ def ecdf( are sorted by the value `x` (or `y` if `orientation` is `'h'`) and their cumulative count (or the cumulative sum of `y` if supplied and `orientation` is `h`) is drawn as a line. + + Parameters + ---------- + data_frame : DataFrame or array-like or dict + This argument needs to be passed for column names (and not keyword + names) to be used. Array-like and dict are transformed internally to a + pandas DataFrame. Optional: if missing, a DataFrame gets constructed + under the hood using the other arguments. + x : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + position marks along the x axis in cartesian coordinates. If + `orientation` is `'h'`, the cumulative sum of this argument is plotted + rather than the cumulative count. Either `x` or `y` can optionally be a + list of column references or array_likes, in which case the data will + be treated as if it were 'wide' rather than 'long'. + y : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + position marks along the y axis in cartesian coordinates. If + `orientation` is `'v'`, the cumulative sum of this argument is plotted + rather than the cumulative count. Either `x` or `y` can optionally be a + list of column references or array_likes, in which case the data will + be treated as if it were 'wide' rather than 'long'. + color : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign color to marks. + text : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like appear in the + figure as text labels. + line_dash : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign dash-patterns to lines. + symbol : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign symbols to marks. + facet_row : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign marks to facetted subplots in the vertical direction. + facet_col : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign marks to facetted subplots in the horizontal direction. + facet_col_wrap : int + Maximum number of facet columns. Wraps the column variable at this + width, so that the column facets span multiple rows. Ignored if 0, and + forced to 0 if `facet_row` or a `marginal` is set. + facet_row_spacing : float between 0 and 1 + Spacing between facet rows, in paper units. Default is 0.03 or 0.07 + when facet_col_wrap is used. + facet_col_spacing : float between 0 and 1 + Spacing between facet columns, in paper units Default is 0.02. + hover_name : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like appear in bold + in the hover tooltip. + hover_data : str, or list of str or int, or Series or array-like, or dict + Either a name or list of names of columns in `data_frame`, or pandas + Series, or array_like objects or a dict with column names as keys, with + values True (for default formatting) False (in order to remove this + column from hover information), or a formatting string, for example + ':.3f' or '|%a' or list-like data to appear in the hover tooltip or + tuples with a bool or formatting string as first element, and list-like + data to appear in hover as second element Values from these columns + appear as extra data in the hover tooltip. + animation_frame : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign marks to animation frames. + animation_group : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + provide object-constancy across animation frames: rows with matching + `animation_group`s will be treated as if they describe the same object + in each frame. + markers : boolean (default `False`) + If `True`, markers are shown on lines. + lines : boolean (default `True`) + If `False`, lines are not drawn (forced to `True` if `markers` is + `False`). + category_orders : dict with str keys and list of str values (default `{}`) + By default, in Python 3.6+, the order of categorical values in axes, + legends and facets depends on the order in which these values are first + encountered in `data_frame` (and no order is guaranteed by default in + Python below 3.6). This parameter is used to force a specific ordering + of values per column. The keys of this dict should correspond to column + names, and the values should be lists of strings corresponding to the + specific display order desired. + labels : dict with str keys and str values (default `{}`) + By default, column names are used in the figure for axis titles, legend + entries and hovers. This parameter allows this to be overridden. The + keys of this dict should correspond to column names, and the values + should correspond to the desired label to be displayed. + color_discrete_sequence : list of str + Strings should define valid CSS-colors. When `color` is set and the + values in the corresponding column are not numeric, values in that + column are assigned colors by cycling through `color_discrete_sequence` + in the order described in `category_orders`, unless the value of + `color` is a key in `color_discrete_map`. Various useful color + sequences are available in the `plotly.express.colors` submodules, + specifically `plotly.express.colors.qualitative`. + color_discrete_map : dict with str keys and str values (default `{}`) + String values should define valid CSS-colors Used to override + `color_discrete_sequence` to assign a specific colors to marks + corresponding with specific values. Keys in `color_discrete_map` should + be values in the column denoted by `color`. Alternatively, if the + values of `color` are valid colors, the string `'identity'` may be + passed to cause them to be used directly. + line_dash_sequence : list of str + Strings should define valid plotly.js dash-patterns. When `line_dash` + is set, values in that column are assigned dash-patterns by cycling + through `line_dash_sequence` in the order described in + `category_orders`, unless the value of `line_dash` is a key in + `line_dash_map`. + line_dash_map : dict with str keys and str values (default `{}`) + Strings values define plotly.js dash-patterns. Used to override + `line_dash_sequences` to assign a specific dash-patterns to lines + corresponding with specific values. Keys in `line_dash_map` should be + values in the column denoted by `line_dash`. Alternatively, if the + values of `line_dash` are valid line-dash names, the string + `'identity'` may be passed to cause them to be used directly. + symbol_sequence : list of str + Strings should define valid plotly.js symbols. When `symbol` is set, + values in that column are assigned symbols by cycling through + `symbol_sequence` in the order described in `category_orders`, unless + the value of `symbol` is a key in `symbol_map`. + symbol_map : dict with str keys and str values (default `{}`) + String values should define plotly.js symbols Used to override + `symbol_sequence` to assign a specific symbols to marks corresponding + with specific values. Keys in `symbol_map` should be values in the + column denoted by `symbol`. Alternatively, if the values of `symbol` + are valid symbol names, the string `'identity'` may be passed to cause + them to be used directly. + marginal : str + One of `'rug'`, `'box'`, `'violin'`, or `'histogram'`. If set, a + subplot is drawn alongside the main plot, visualizing the distribution. + opacity : float + Value between 0 and 1. Sets the opacity for markers. + orientation : str, one of `'h'` for horizontal or `'v'` for vertical. + (default `'v'` if `x` and `y` are provided and both continuous or both + categorical, otherwise `'v'`(`'h'`) if `x`(`y`) is categorical and + `y`(`x`) is continuous, otherwise `'v'`(`'h'`) if only `x`(`y`) is + provided) + ecdfnorm : string or `None` (default `'probability'`) + One of `'probability'` or `'percent'` If `None`, values will be raw + counts or sums. If `'probability', values will be probabilities + normalized from 0 to 1. If `'percent', values will be percentages + normalized from 0 to 100. + ecdfmode : string (default `'standard'`) + One of `'standard'`, `'complementary'` or `'reversed'` If `'standard'`, + the ECDF is plotted such that values represent data at or below the + point. If `'complementary'`, the CCDF is plotted such that values + represent data above the point. If `'reversed'`, a variant of the CCDF + is plotted such that values represent data at or above the point. + render_mode : str + One of `'auto'`, `'svg'` or `'webgl'`, default `'auto'` Controls the + browser API used to draw marks. `'svg'` is appropriate for figures of + less than 1000 data points, and will allow for fully-vectorized output. + `'webgl'` is likely necessary for acceptable performance above 1000 + points but rasterizes part of the output. `'auto'` uses heuristics to + choose the mode. + log_x : boolean (default `False`) + If `True`, the x-axis is log-scaled in cartesian coordinates. + log_y : boolean (default `False`) + If `True`, the y-axis is log-scaled in cartesian coordinates. + range_x : list of two numbers + If provided, overrides auto-scaling on the x-axis in cartesian + coordinates. + range_y : list of two numbers + If provided, overrides auto-scaling on the y-axis in cartesian + coordinates. + title : str + The figure title. + subtitle : str + The figure subtitle. + template : str or dict or plotly.graph_objects.layout.Template instance + The figure template name (must be a key in plotly.io.templates) or + definition. + width : int (default `None`) + The figure width in pixels. + height : int (default `None`) + The figure height in pixels. + + Returns + ------- + plotly.graph_objects.Figure """ return make_figure(args=locals(), constructor=go.Scatter) -ecdf.__doc__ = make_docstring( - ecdf, - append_dict=dict( - x=[ - "If `orientation` is `'h'`, the cumulative sum of this argument is plotted rather than the cumulative count." - ] - + _wide_mode_xy_append, - y=[ - "If `orientation` is `'v'`, the cumulative sum of this argument is plotted rather than the cumulative count." - ] - + _wide_mode_xy_append, - ), -) - - def violin( data_frame=None, x=None, @@ -616,6 +2243,151 @@ def violin( """ In a violin plot, rows of `data_frame` are grouped together into a curved mark to visualize their distribution. + + Parameters + ---------- + data_frame : DataFrame or array-like or dict + This argument needs to be passed for column names (and not keyword + names) to be used. Array-like and dict are transformed internally to a + pandas DataFrame. Optional: if missing, a DataFrame gets constructed + under the hood using the other arguments. + x : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + position marks along the x axis in cartesian coordinates. Either `x` or + `y` can optionally be a list of column references or array_likes, in + which case the data will be treated as if it were 'wide' rather than + 'long'. + y : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + position marks along the y axis in cartesian coordinates. Either `x` or + `y` can optionally be a list of column references or array_likes, in + which case the data will be treated as if it were 'wide' rather than + 'long'. + color : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign color to marks. + facet_row : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign marks to facetted subplots in the vertical direction. + facet_col : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign marks to facetted subplots in the horizontal direction. + facet_col_wrap : int + Maximum number of facet columns. Wraps the column variable at this + width, so that the column facets span multiple rows. Ignored if 0, and + forced to 0 if `facet_row` or a `marginal` is set. + facet_row_spacing : float between 0 and 1 + Spacing between facet rows, in paper units. Default is 0.03 or 0.07 + when facet_col_wrap is used. + facet_col_spacing : float between 0 and 1 + Spacing between facet columns, in paper units Default is 0.02. + hover_name : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like appear in bold + in the hover tooltip. + hover_data : str, or list of str or int, or Series or array-like, or dict + Either a name or list of names of columns in `data_frame`, or pandas + Series, or array_like objects or a dict with column names as keys, with + values True (for default formatting) False (in order to remove this + column from hover information), or a formatting string, for example + ':.3f' or '|%a' or list-like data to appear in the hover tooltip or + tuples with a bool or formatting string as first element, and list-like + data to appear in hover as second element Values from these columns + appear as extra data in the hover tooltip. + custom_data : str, or list of str or int, or Series or array-like + Either name or list of names of columns in `data_frame`, or pandas + Series, or array_like objects Values from these columns are extra data, + to be used in widgets or Dash callbacks for example. This data is not + user-visible but is included in events emitted by the figure (lasso + selection etc.) + animation_frame : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign marks to animation frames. + animation_group : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + provide object-constancy across animation frames: rows with matching + `animation_group`s will be treated as if they describe the same object + in each frame. + category_orders : dict with str keys and list of str values (default `{}`) + By default, in Python 3.6+, the order of categorical values in axes, + legends and facets depends on the order in which these values are first + encountered in `data_frame` (and no order is guaranteed by default in + Python below 3.6). This parameter is used to force a specific ordering + of values per column. The keys of this dict should correspond to column + names, and the values should be lists of strings corresponding to the + specific display order desired. + labels : dict with str keys and str values (default `{}`) + By default, column names are used in the figure for axis titles, legend + entries and hovers. This parameter allows this to be overridden. The + keys of this dict should correspond to column names, and the values + should correspond to the desired label to be displayed. + color_discrete_sequence : list of str + Strings should define valid CSS-colors. When `color` is set and the + values in the corresponding column are not numeric, values in that + column are assigned colors by cycling through `color_discrete_sequence` + in the order described in `category_orders`, unless the value of + `color` is a key in `color_discrete_map`. Various useful color + sequences are available in the `plotly.express.colors` submodules, + specifically `plotly.express.colors.qualitative`. + color_discrete_map : dict with str keys and str values (default `{}`) + String values should define valid CSS-colors Used to override + `color_discrete_sequence` to assign a specific colors to marks + corresponding with specific values. Keys in `color_discrete_map` should + be values in the column denoted by `color`. Alternatively, if the + values of `color` are valid colors, the string `'identity'` may be + passed to cause them to be used directly. + orientation : str, one of `'h'` for horizontal or `'v'` for vertical. + (default `'v'` if `x` and `y` are provided and both continuous or both + categorical, otherwise `'v'`(`'h'`) if `x`(`y`) is categorical and + `y`(`x`) is continuous, otherwise `'v'`(`'h'`) if only `x`(`y`) is + provided) + violinmode : str (default `'group'`) + One of `'group'` or `'overlay'` In `'overlay'` mode, violins are on + drawn top of one another. In `'group'` mode, violins are placed beside + each other. + log_x : boolean (default `False`) + If `True`, the x-axis is log-scaled in cartesian coordinates. + log_y : boolean (default `False`) + If `True`, the y-axis is log-scaled in cartesian coordinates. + range_x : list of two numbers + If provided, overrides auto-scaling on the x-axis in cartesian + coordinates. + range_y : list of two numbers + If provided, overrides auto-scaling on the y-axis in cartesian + coordinates. + points : str or boolean (default `'outliers'`) + One of `'outliers'`, `'suspectedoutliers'`, `'all'`, or `False`. If + `'outliers'`, only the sample points lying outside the whiskers are + shown. If `'suspectedoutliers'`, all outlier points are shown and those + less than 4*Q1-3*Q3 or greater than 4*Q3-3*Q1 are highlighted with the + marker's `'outliercolor'`. If `'outliers'`, only the sample points + lying outside the whiskers are shown. If `'all'`, all sample points are + shown. If `False`, no sample points are shown and the whiskers extend + to the full range of the sample. + box : boolean (default `False`) + If `True`, boxes are drawn inside the violins. + title : str + The figure title. + subtitle : str + The figure subtitle. + template : str or dict or plotly.graph_objects.layout.Template instance + The figure template name (must be a key in plotly.io.templates) or + definition. + width : int (default `None`) + The figure width in pixels. + height : int (default `None`) + The figure height in pixels. + + Returns + ------- + plotly.graph_objects.Figure """ return make_figure( args=locals(), @@ -631,9 +2403,6 @@ def violin( ) -violin.__doc__ = make_docstring(violin, append_dict=_cartesian_append_dict) - - def box( data_frame=None, x=None, @@ -675,6 +2444,151 @@ def box( quartile (Q2) is marked by a line inside the box. By default, the whiskers correspond to the box' edges +/- 1.5 times the interquartile range (IQR: Q3-Q1), see "points" for other options. + + Parameters + ---------- + data_frame : DataFrame or array-like or dict + This argument needs to be passed for column names (and not keyword + names) to be used. Array-like and dict are transformed internally to a + pandas DataFrame. Optional: if missing, a DataFrame gets constructed + under the hood using the other arguments. + x : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + position marks along the x axis in cartesian coordinates. Either `x` or + `y` can optionally be a list of column references or array_likes, in + which case the data will be treated as if it were 'wide' rather than + 'long'. + y : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + position marks along the y axis in cartesian coordinates. Either `x` or + `y` can optionally be a list of column references or array_likes, in + which case the data will be treated as if it were 'wide' rather than + 'long'. + color : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign color to marks. + facet_row : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign marks to facetted subplots in the vertical direction. + facet_col : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign marks to facetted subplots in the horizontal direction. + facet_col_wrap : int + Maximum number of facet columns. Wraps the column variable at this + width, so that the column facets span multiple rows. Ignored if 0, and + forced to 0 if `facet_row` or a `marginal` is set. + facet_row_spacing : float between 0 and 1 + Spacing between facet rows, in paper units. Default is 0.03 or 0.07 + when facet_col_wrap is used. + facet_col_spacing : float between 0 and 1 + Spacing between facet columns, in paper units Default is 0.02. + hover_name : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like appear in bold + in the hover tooltip. + hover_data : str, or list of str or int, or Series or array-like, or dict + Either a name or list of names of columns in `data_frame`, or pandas + Series, or array_like objects or a dict with column names as keys, with + values True (for default formatting) False (in order to remove this + column from hover information), or a formatting string, for example + ':.3f' or '|%a' or list-like data to appear in the hover tooltip or + tuples with a bool or formatting string as first element, and list-like + data to appear in hover as second element Values from these columns + appear as extra data in the hover tooltip. + custom_data : str, or list of str or int, or Series or array-like + Either name or list of names of columns in `data_frame`, or pandas + Series, or array_like objects Values from these columns are extra data, + to be used in widgets or Dash callbacks for example. This data is not + user-visible but is included in events emitted by the figure (lasso + selection etc.) + animation_frame : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign marks to animation frames. + animation_group : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + provide object-constancy across animation frames: rows with matching + `animation_group`s will be treated as if they describe the same object + in each frame. + category_orders : dict with str keys and list of str values (default `{}`) + By default, in Python 3.6+, the order of categorical values in axes, + legends and facets depends on the order in which these values are first + encountered in `data_frame` (and no order is guaranteed by default in + Python below 3.6). This parameter is used to force a specific ordering + of values per column. The keys of this dict should correspond to column + names, and the values should be lists of strings corresponding to the + specific display order desired. + labels : dict with str keys and str values (default `{}`) + By default, column names are used in the figure for axis titles, legend + entries and hovers. This parameter allows this to be overridden. The + keys of this dict should correspond to column names, and the values + should correspond to the desired label to be displayed. + color_discrete_sequence : list of str + Strings should define valid CSS-colors. When `color` is set and the + values in the corresponding column are not numeric, values in that + column are assigned colors by cycling through `color_discrete_sequence` + in the order described in `category_orders`, unless the value of + `color` is a key in `color_discrete_map`. Various useful color + sequences are available in the `plotly.express.colors` submodules, + specifically `plotly.express.colors.qualitative`. + color_discrete_map : dict with str keys and str values (default `{}`) + String values should define valid CSS-colors Used to override + `color_discrete_sequence` to assign a specific colors to marks + corresponding with specific values. Keys in `color_discrete_map` should + be values in the column denoted by `color`. Alternatively, if the + values of `color` are valid colors, the string `'identity'` may be + passed to cause them to be used directly. + orientation : str, one of `'h'` for horizontal or `'v'` for vertical. + (default `'v'` if `x` and `y` are provided and both continuous or both + categorical, otherwise `'v'`(`'h'`) if `x`(`y`) is categorical and + `y`(`x`) is continuous, otherwise `'v'`(`'h'`) if only `x`(`y`) is + provided) + boxmode : str (default `'group'`) + One of `'group'` or `'overlay'` In `'overlay'` mode, boxes are on drawn + top of one another. In `'group'` mode, boxes are placed beside each + other. + log_x : boolean (default `False`) + If `True`, the x-axis is log-scaled in cartesian coordinates. + log_y : boolean (default `False`) + If `True`, the y-axis is log-scaled in cartesian coordinates. + range_x : list of two numbers + If provided, overrides auto-scaling on the x-axis in cartesian + coordinates. + range_y : list of two numbers + If provided, overrides auto-scaling on the y-axis in cartesian + coordinates. + points : str or boolean (default `'outliers'`) + One of `'outliers'`, `'suspectedoutliers'`, `'all'`, or `False`. If + `'outliers'`, only the sample points lying outside the whiskers are + shown. If `'suspectedoutliers'`, all outlier points are shown and those + less than 4*Q1-3*Q3 or greater than 4*Q3-3*Q1 are highlighted with the + marker's `'outliercolor'`. If `'outliers'`, only the sample points + lying outside the whiskers are shown. If `'all'`, all sample points are + shown. If `False`, no sample points are shown and the whiskers extend + to the full range of the sample. + notched : boolean (default `False`) + If `True`, boxes are drawn with notches. + title : str + The figure title. + subtitle : str + The figure subtitle. + template : str or dict or plotly.graph_objects.layout.Template instance + The figure template name (must be a key in plotly.io.templates) or + definition. + width : int (default `None`) + The figure width in pixels. + height : int (default `None`) + The figure height in pixels. + + Returns + ------- + plotly.graph_objects.Figure """ return make_figure( args=locals(), @@ -684,9 +2598,6 @@ def box( ) -box.__doc__ = make_docstring(box, append_dict=_cartesian_append_dict) - - def strip( data_frame=None, x=None, @@ -721,6 +2632,140 @@ def strip( """ In a strip plot each row of `data_frame` is represented as a jittered mark within categories. + + Parameters + ---------- + data_frame : DataFrame or array-like or dict + This argument needs to be passed for column names (and not keyword + names) to be used. Array-like and dict are transformed internally to a + pandas DataFrame. Optional: if missing, a DataFrame gets constructed + under the hood using the other arguments. + x : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + position marks along the x axis in cartesian coordinates. Either `x` or + `y` can optionally be a list of column references or array_likes, in + which case the data will be treated as if it were 'wide' rather than + 'long'. + y : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + position marks along the y axis in cartesian coordinates. Either `x` or + `y` can optionally be a list of column references or array_likes, in + which case the data will be treated as if it were 'wide' rather than + 'long'. + color : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign color to marks. + facet_row : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign marks to facetted subplots in the vertical direction. + facet_col : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign marks to facetted subplots in the horizontal direction. + facet_col_wrap : int + Maximum number of facet columns. Wraps the column variable at this + width, so that the column facets span multiple rows. Ignored if 0, and + forced to 0 if `facet_row` or a `marginal` is set. + facet_row_spacing : float between 0 and 1 + Spacing between facet rows, in paper units. Default is 0.03 or 0.07 + when facet_col_wrap is used. + facet_col_spacing : float between 0 and 1 + Spacing between facet columns, in paper units Default is 0.02. + hover_name : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like appear in bold + in the hover tooltip. + hover_data : str, or list of str or int, or Series or array-like, or dict + Either a name or list of names of columns in `data_frame`, or pandas + Series, or array_like objects or a dict with column names as keys, with + values True (for default formatting) False (in order to remove this + column from hover information), or a formatting string, for example + ':.3f' or '|%a' or list-like data to appear in the hover tooltip or + tuples with a bool or formatting string as first element, and list-like + data to appear in hover as second element Values from these columns + appear as extra data in the hover tooltip. + custom_data : str, or list of str or int, or Series or array-like + Either name or list of names of columns in `data_frame`, or pandas + Series, or array_like objects Values from these columns are extra data, + to be used in widgets or Dash callbacks for example. This data is not + user-visible but is included in events emitted by the figure (lasso + selection etc.) + animation_frame : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign marks to animation frames. + animation_group : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + provide object-constancy across animation frames: rows with matching + `animation_group`s will be treated as if they describe the same object + in each frame. + category_orders : dict with str keys and list of str values (default `{}`) + By default, in Python 3.6+, the order of categorical values in axes, + legends and facets depends on the order in which these values are first + encountered in `data_frame` (and no order is guaranteed by default in + Python below 3.6). This parameter is used to force a specific ordering + of values per column. The keys of this dict should correspond to column + names, and the values should be lists of strings corresponding to the + specific display order desired. + labels : dict with str keys and str values (default `{}`) + By default, column names are used in the figure for axis titles, legend + entries and hovers. This parameter allows this to be overridden. The + keys of this dict should correspond to column names, and the values + should correspond to the desired label to be displayed. + color_discrete_sequence : list of str + Strings should define valid CSS-colors. When `color` is set and the + values in the corresponding column are not numeric, values in that + column are assigned colors by cycling through `color_discrete_sequence` + in the order described in `category_orders`, unless the value of + `color` is a key in `color_discrete_map`. Various useful color + sequences are available in the `plotly.express.colors` submodules, + specifically `plotly.express.colors.qualitative`. + color_discrete_map : dict with str keys and str values (default `{}`) + String values should define valid CSS-colors Used to override + `color_discrete_sequence` to assign a specific colors to marks + corresponding with specific values. Keys in `color_discrete_map` should + be values in the column denoted by `color`. Alternatively, if the + values of `color` are valid colors, the string `'identity'` may be + passed to cause them to be used directly. + orientation : str, one of `'h'` for horizontal or `'v'` for vertical. + (default `'v'` if `x` and `y` are provided and both continuous or both + categorical, otherwise `'v'`(`'h'`) if `x`(`y`) is categorical and + `y`(`x`) is continuous, otherwise `'v'`(`'h'`) if only `x`(`y`) is + provided) + stripmode: str (default `'group'`) + One of `'group'` or `'overlay'` In `'overlay'` mode, strips are on + drawn top of one another. In `'group'` mode, strips are placed beside + each other. + log_x : boolean (default `False`) + If `True`, the x-axis is log-scaled in cartesian coordinates. + log_y : boolean (default `False`) + If `True`, the y-axis is log-scaled in cartesian coordinates. + range_x : list of two numbers + If provided, overrides auto-scaling on the x-axis in cartesian + coordinates. + range_y : list of two numbers + If provided, overrides auto-scaling on the y-axis in cartesian + coordinates. + title : str + The figure title. + subtitle : str + The figure subtitle. + template : str or dict or plotly.graph_objects.layout.Template instance + The figure template name (must be a key in plotly.io.templates) or + definition. + width : int (default `None`) + The figure width in pixels. + height : int (default `None`) + The figure height in pixels. + + Returns + ------- + plotly.graph_objects.Figure """ return make_figure( args=locals(), @@ -738,9 +2783,6 @@ def strip( ) -strip.__doc__ = make_docstring(strip, append_dict=_cartesian_append_dict) - - def scatter_3d( data_frame=None, x=None, @@ -787,13 +2829,196 @@ def scatter_3d( """ In a 3D scatter plot, each row of `data_frame` is represented by a symbol mark in 3D space. + + Parameters + ---------- + data_frame : DataFrame or array-like or dict + This argument needs to be passed for column names (and not keyword + names) to be used. Array-like and dict are transformed internally to a + pandas DataFrame. Optional: if missing, a DataFrame gets constructed + under the hood using the other arguments. + x : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + position marks along the x axis in cartesian coordinates. + y : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + position marks along the y axis in cartesian coordinates. + z : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + position marks along the z axis in cartesian coordinates. + color : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign color to marks. + symbol : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign symbols to marks. + size : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign mark sizes. + text : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like appear in the + figure as text labels. + hover_name : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like appear in bold + in the hover tooltip. + hover_data : str, or list of str or int, or Series or array-like, or dict + Either a name or list of names of columns in `data_frame`, or pandas + Series, or array_like objects or a dict with column names as keys, with + values True (for default formatting) False (in order to remove this + column from hover information), or a formatting string, for example + ':.3f' or '|%a' or list-like data to appear in the hover tooltip or + tuples with a bool or formatting string as first element, and list-like + data to appear in hover as second element Values from these columns + appear as extra data in the hover tooltip. + custom_data : str, or list of str or int, or Series or array-like + Either name or list of names of columns in `data_frame`, or pandas + Series, or array_like objects Values from these columns are extra data, + to be used in widgets or Dash callbacks for example. This data is not + user-visible but is included in events emitted by the figure (lasso + selection etc.) + error_x : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + size x-axis error bars. If `error_x_minus` is `None`, error bars will + be symmetrical, otherwise `error_x` is used for the positive direction + only. + error_x_minus : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + size x-axis error bars in the negative direction. Ignored if `error_x` + is `None`. + error_y : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + size y-axis error bars. If `error_y_minus` is `None`, error bars will + be symmetrical, otherwise `error_y` is used for the positive direction + only. + error_y_minus : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + size y-axis error bars in the negative direction. Ignored if `error_y` + is `None`. + error_z : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + size z-axis error bars. If `error_z_minus` is `None`, error bars will + be symmetrical, otherwise `error_z` is used for the positive direction + only. + error_z_minus : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + size z-axis error bars in the negative direction. Ignored if `error_z` + is `None`. + animation_frame : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign marks to animation frames. + animation_group : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + provide object-constancy across animation frames: rows with matching + `animation_group`s will be treated as if they describe the same object + in each frame. + category_orders : dict with str keys and list of str values (default `{}`) + By default, in Python 3.6+, the order of categorical values in axes, + legends and facets depends on the order in which these values are first + encountered in `data_frame` (and no order is guaranteed by default in + Python below 3.6). This parameter is used to force a specific ordering + of values per column. The keys of this dict should correspond to column + names, and the values should be lists of strings corresponding to the + specific display order desired. + labels : dict with str keys and str values (default `{}`) + By default, column names are used in the figure for axis titles, legend + entries and hovers. This parameter allows this to be overridden. The + keys of this dict should correspond to column names, and the values + should correspond to the desired label to be displayed. + size_max : int (default `20`) + Set the maximum mark size when using `size`. + color_discrete_sequence : list of str + Strings should define valid CSS-colors. When `color` is set and the + values in the corresponding column are not numeric, values in that + column are assigned colors by cycling through `color_discrete_sequence` + in the order described in `category_orders`, unless the value of + `color` is a key in `color_discrete_map`. Various useful color + sequences are available in the `plotly.express.colors` submodules, + specifically `plotly.express.colors.qualitative`. + color_discrete_map : dict with str keys and str values (default `{}`) + String values should define valid CSS-colors Used to override + `color_discrete_sequence` to assign a specific colors to marks + corresponding with specific values. Keys in `color_discrete_map` should + be values in the column denoted by `color`. Alternatively, if the + values of `color` are valid colors, the string `'identity'` may be + passed to cause them to be used directly. + color_continuous_scale : list of str + Strings should define valid CSS-colors This list is used to build a + continuous color scale when the column denoted by `color` contains + numeric data. Various useful color scales are available in the + `plotly.express.colors` submodules, specifically + `plotly.express.colors.sequential`, `plotly.express.colors.diverging` + and `plotly.express.colors.cyclical`. + range_color : list of two numbers + If provided, overrides auto-scaling on the continuous color scale. + color_continuous_midpoint : number (default `None`) + If set, computes the bounds of the continuous color scale to have the + desired midpoint. Setting this value is recommended when using + `plotly.express.colors.diverging` color scales as the inputs to + `color_continuous_scale`. + symbol_sequence : list of str + Strings should define valid plotly.js symbols. When `symbol` is set, + values in that column are assigned symbols by cycling through + `symbol_sequence` in the order described in `category_orders`, unless + the value of `symbol` is a key in `symbol_map`. + symbol_map : dict with str keys and str values (default `{}`) + String values should define plotly.js symbols Used to override + `symbol_sequence` to assign a specific symbols to marks corresponding + with specific values. Keys in `symbol_map` should be values in the + column denoted by `symbol`. Alternatively, if the values of `symbol` + are valid symbol names, the string `'identity'` may be passed to cause + them to be used directly. + opacity : float + Value between 0 and 1. Sets the opacity for markers. + log_x : boolean (default `False`) + If `True`, the x-axis is log-scaled in cartesian coordinates. + log_y : boolean (default `False`) + If `True`, the y-axis is log-scaled in cartesian coordinates. + log_z : boolean (default `False`) + If `True`, the z-axis is log-scaled in cartesian coordinates. + range_x : list of two numbers + If provided, overrides auto-scaling on the x-axis in cartesian + coordinates. + range_y : list of two numbers + If provided, overrides auto-scaling on the y-axis in cartesian + coordinates. + range_z : list of two numbers + If provided, overrides auto-scaling on the z-axis in cartesian + coordinates. + title : str + The figure title. + subtitle : str + The figure subtitle. + template : str or dict or plotly.graph_objects.layout.Template instance + The figure template name (must be a key in plotly.io.templates) or + definition. + width : int (default `None`) + The figure width in pixels. + height : int (default `None`) + The figure height in pixels. + + Returns + ------- + plotly.graph_objects.Figure """ return make_figure(args=locals(), constructor=go.Scatter3d) -scatter_3d.__doc__ = make_docstring(scatter_3d) - - def line_3d( data_frame=None, x=None, @@ -839,13 +3064,197 @@ def line_3d( """ In a 3D line plot, each row of `data_frame` is represented as a vertex of a polyline mark in 3D space. + + Parameters + ---------- + data_frame : DataFrame or array-like or dict + This argument needs to be passed for column names (and not keyword + names) to be used. Array-like and dict are transformed internally to a + pandas DataFrame. Optional: if missing, a DataFrame gets constructed + under the hood using the other arguments. + x : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + position marks along the x axis in cartesian coordinates. + y : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + position marks along the y axis in cartesian coordinates. + z : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + position marks along the z axis in cartesian coordinates. + color : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign color to marks. + line_dash : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign dash-patterns to lines. + text : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like appear in the + figure as text labels. + line_group : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + group rows of `data_frame` into lines. + symbol : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign symbols to marks. + hover_name : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like appear in bold + in the hover tooltip. + hover_data : str, or list of str or int, or Series or array-like, or dict + Either a name or list of names of columns in `data_frame`, or pandas + Series, or array_like objects or a dict with column names as keys, with + values True (for default formatting) False (in order to remove this + column from hover information), or a formatting string, for example + ':.3f' or '|%a' or list-like data to appear in the hover tooltip or + tuples with a bool or formatting string as first element, and list-like + data to appear in hover as second element Values from these columns + appear as extra data in the hover tooltip. + custom_data : str, or list of str or int, or Series or array-like + Either name or list of names of columns in `data_frame`, or pandas + Series, or array_like objects Values from these columns are extra data, + to be used in widgets or Dash callbacks for example. This data is not + user-visible but is included in events emitted by the figure (lasso + selection etc.) + error_x : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + size x-axis error bars. If `error_x_minus` is `None`, error bars will + be symmetrical, otherwise `error_x` is used for the positive direction + only. + error_x_minus : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + size x-axis error bars in the negative direction. Ignored if `error_x` + is `None`. + error_y : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + size y-axis error bars. If `error_y_minus` is `None`, error bars will + be symmetrical, otherwise `error_y` is used for the positive direction + only. + error_y_minus : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + size y-axis error bars in the negative direction. Ignored if `error_y` + is `None`. + error_z : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + size z-axis error bars. If `error_z_minus` is `None`, error bars will + be symmetrical, otherwise `error_z` is used for the positive direction + only. + error_z_minus : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + size z-axis error bars in the negative direction. Ignored if `error_z` + is `None`. + animation_frame : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign marks to animation frames. + animation_group : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + provide object-constancy across animation frames: rows with matching + `animation_group`s will be treated as if they describe the same object + in each frame. + category_orders : dict with str keys and list of str values (default `{}`) + By default, in Python 3.6+, the order of categorical values in axes, + legends and facets depends on the order in which these values are first + encountered in `data_frame` (and no order is guaranteed by default in + Python below 3.6). This parameter is used to force a specific ordering + of values per column. The keys of this dict should correspond to column + names, and the values should be lists of strings corresponding to the + specific display order desired. + labels : dict with str keys and str values (default `{}`) + By default, column names are used in the figure for axis titles, legend + entries and hovers. This parameter allows this to be overridden. The + keys of this dict should correspond to column names, and the values + should correspond to the desired label to be displayed. + color_discrete_sequence : list of str + Strings should define valid CSS-colors. When `color` is set and the + values in the corresponding column are not numeric, values in that + column are assigned colors by cycling through `color_discrete_sequence` + in the order described in `category_orders`, unless the value of + `color` is a key in `color_discrete_map`. Various useful color + sequences are available in the `plotly.express.colors` submodules, + specifically `plotly.express.colors.qualitative`. + color_discrete_map : dict with str keys and str values (default `{}`) + String values should define valid CSS-colors Used to override + `color_discrete_sequence` to assign a specific colors to marks + corresponding with specific values. Keys in `color_discrete_map` should + be values in the column denoted by `color`. Alternatively, if the + values of `color` are valid colors, the string `'identity'` may be + passed to cause them to be used directly. + line_dash_sequence : list of str + Strings should define valid plotly.js dash-patterns. When `line_dash` + is set, values in that column are assigned dash-patterns by cycling + through `line_dash_sequence` in the order described in + `category_orders`, unless the value of `line_dash` is a key in + `line_dash_map`. + line_dash_map : dict with str keys and str values (default `{}`) + Strings values define plotly.js dash-patterns. Used to override + `line_dash_sequences` to assign a specific dash-patterns to lines + corresponding with specific values. Keys in `line_dash_map` should be + values in the column denoted by `line_dash`. Alternatively, if the + values of `line_dash` are valid line-dash names, the string + `'identity'` may be passed to cause them to be used directly. + symbol_sequence : list of str + Strings should define valid plotly.js symbols. When `symbol` is set, + values in that column are assigned symbols by cycling through + `symbol_sequence` in the order described in `category_orders`, unless + the value of `symbol` is a key in `symbol_map`. + symbol_map : dict with str keys and str values (default `{}`) + String values should define plotly.js symbols Used to override + `symbol_sequence` to assign a specific symbols to marks corresponding + with specific values. Keys in `symbol_map` should be values in the + column denoted by `symbol`. Alternatively, if the values of `symbol` + are valid symbol names, the string `'identity'` may be passed to cause + them to be used directly. + markers : boolean (default `False`) + If `True`, markers are shown on lines. + log_x : boolean (default `False`) + If `True`, the x-axis is log-scaled in cartesian coordinates. + log_y : boolean (default `False`) + If `True`, the y-axis is log-scaled in cartesian coordinates. + log_z : boolean (default `False`) + If `True`, the z-axis is log-scaled in cartesian coordinates. + range_x : list of two numbers + If provided, overrides auto-scaling on the x-axis in cartesian + coordinates. + range_y : list of two numbers + If provided, overrides auto-scaling on the y-axis in cartesian + coordinates. + range_z : list of two numbers + If provided, overrides auto-scaling on the z-axis in cartesian + coordinates. + title : str + The figure title. + subtitle : str + The figure subtitle. + template : str or dict or plotly.graph_objects.layout.Template instance + The figure template name (must be a key in plotly.io.templates) or + definition. + width : int (default `None`) + The figure width in pixels. + height : int (default `None`) + The figure height in pixels. + + Returns + ------- + plotly.graph_objects.Figure """ return make_figure(args=locals(), constructor=go.Scatter3d) -line_3d.__doc__ = make_docstring(line_3d) - - def scatter_ternary( data_frame=None, a=None, @@ -880,13 +3289,148 @@ def scatter_ternary( """ In a ternary scatter plot, each row of `data_frame` is represented by a symbol mark in ternary coordinates. + + Parameters + ---------- + data_frame : DataFrame or array-like or dict + This argument needs to be passed for column names (and not keyword + names) to be used. Array-like and dict are transformed internally to a + pandas DataFrame. Optional: if missing, a DataFrame gets constructed + under the hood using the other arguments. + a : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + position marks along the a axis in ternary coordinates. + b : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + position marks along the b axis in ternary coordinates. + c : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + position marks along the c axis in ternary coordinates. + color : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign color to marks. + symbol : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign symbols to marks. + size : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign mark sizes. + text : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like appear in the + figure as text labels. + hover_name : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like appear in bold + in the hover tooltip. + hover_data : str, or list of str or int, or Series or array-like, or dict + Either a name or list of names of columns in `data_frame`, or pandas + Series, or array_like objects or a dict with column names as keys, with + values True (for default formatting) False (in order to remove this + column from hover information), or a formatting string, for example + ':.3f' or '|%a' or list-like data to appear in the hover tooltip or + tuples with a bool or formatting string as first element, and list-like + data to appear in hover as second element Values from these columns + appear as extra data in the hover tooltip. + custom_data : str, or list of str or int, or Series or array-like + Either name or list of names of columns in `data_frame`, or pandas + Series, or array_like objects Values from these columns are extra data, + to be used in widgets or Dash callbacks for example. This data is not + user-visible but is included in events emitted by the figure (lasso + selection etc.) + animation_frame : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign marks to animation frames. + animation_group : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + provide object-constancy across animation frames: rows with matching + `animation_group`s will be treated as if they describe the same object + in each frame. + category_orders : dict with str keys and list of str values (default `{}`) + By default, in Python 3.6+, the order of categorical values in axes, + legends and facets depends on the order in which these values are first + encountered in `data_frame` (and no order is guaranteed by default in + Python below 3.6). This parameter is used to force a specific ordering + of values per column. The keys of this dict should correspond to column + names, and the values should be lists of strings corresponding to the + specific display order desired. + labels : dict with str keys and str values (default `{}`) + By default, column names are used in the figure for axis titles, legend + entries and hovers. This parameter allows this to be overridden. The + keys of this dict should correspond to column names, and the values + should correspond to the desired label to be displayed. + color_discrete_sequence : list of str + Strings should define valid CSS-colors. When `color` is set and the + values in the corresponding column are not numeric, values in that + column are assigned colors by cycling through `color_discrete_sequence` + in the order described in `category_orders`, unless the value of + `color` is a key in `color_discrete_map`. Various useful color + sequences are available in the `plotly.express.colors` submodules, + specifically `plotly.express.colors.qualitative`. + color_discrete_map : dict with str keys and str values (default `{}`) + String values should define valid CSS-colors Used to override + `color_discrete_sequence` to assign a specific colors to marks + corresponding with specific values. Keys in `color_discrete_map` should + be values in the column denoted by `color`. Alternatively, if the + values of `color` are valid colors, the string `'identity'` may be + passed to cause them to be used directly. + color_continuous_scale : list of str + Strings should define valid CSS-colors This list is used to build a + continuous color scale when the column denoted by `color` contains + numeric data. Various useful color scales are available in the + `plotly.express.colors` submodules, specifically + `plotly.express.colors.sequential`, `plotly.express.colors.diverging` + and `plotly.express.colors.cyclical`. + range_color : list of two numbers + If provided, overrides auto-scaling on the continuous color scale. + color_continuous_midpoint : number (default `None`) + If set, computes the bounds of the continuous color scale to have the + desired midpoint. Setting this value is recommended when using + `plotly.express.colors.diverging` color scales as the inputs to + `color_continuous_scale`. + symbol_sequence : list of str + Strings should define valid plotly.js symbols. When `symbol` is set, + values in that column are assigned symbols by cycling through + `symbol_sequence` in the order described in `category_orders`, unless + the value of `symbol` is a key in `symbol_map`. + symbol_map : dict with str keys and str values (default `{}`) + String values should define plotly.js symbols Used to override + `symbol_sequence` to assign a specific symbols to marks corresponding + with specific values. Keys in `symbol_map` should be values in the + column denoted by `symbol`. Alternatively, if the values of `symbol` + are valid symbol names, the string `'identity'` may be passed to cause + them to be used directly. + opacity : float + Value between 0 and 1. Sets the opacity for markers. + size_max : int (default `20`) + Set the maximum mark size when using `size`. + title : str + The figure title. + subtitle : str + The figure subtitle. + template : str or dict or plotly.graph_objects.layout.Template instance + The figure template name (must be a key in plotly.io.templates) or + definition. + width : int (default `None`) + The figure width in pixels. + height : int (default `None`) + The figure height in pixels. + + Returns + ------- + plotly.graph_objects.Figure """ return make_figure(args=locals(), constructor=go.Scatterternary) -scatter_ternary.__doc__ = make_docstring(scatter_ternary) - - def line_ternary( data_frame=None, a=None, @@ -921,13 +3465,151 @@ def line_ternary( """ In a ternary line plot, each row of `data_frame` is represented as a vertex of a polyline mark in ternary coordinates. + + Parameters + ---------- + data_frame : DataFrame or array-like or dict + This argument needs to be passed for column names (and not keyword + names) to be used. Array-like and dict are transformed internally to a + pandas DataFrame. Optional: if missing, a DataFrame gets constructed + under the hood using the other arguments. + a : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + position marks along the a axis in ternary coordinates. + b : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + position marks along the b axis in ternary coordinates. + c : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + position marks along the c axis in ternary coordinates. + color : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign color to marks. + line_dash : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign dash-patterns to lines. + line_group : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + group rows of `data_frame` into lines. + symbol : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign symbols to marks. + hover_name : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like appear in bold + in the hover tooltip. + hover_data : str, or list of str or int, or Series or array-like, or dict + Either a name or list of names of columns in `data_frame`, or pandas + Series, or array_like objects or a dict with column names as keys, with + values True (for default formatting) False (in order to remove this + column from hover information), or a formatting string, for example + ':.3f' or '|%a' or list-like data to appear in the hover tooltip or + tuples with a bool or formatting string as first element, and list-like + data to appear in hover as second element Values from these columns + appear as extra data in the hover tooltip. + custom_data : str, or list of str or int, or Series or array-like + Either name or list of names of columns in `data_frame`, or pandas + Series, or array_like objects Values from these columns are extra data, + to be used in widgets or Dash callbacks for example. This data is not + user-visible but is included in events emitted by the figure (lasso + selection etc.) + text : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like appear in the + figure as text labels. + animation_frame : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign marks to animation frames. + animation_group : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + provide object-constancy across animation frames: rows with matching + `animation_group`s will be treated as if they describe the same object + in each frame. + category_orders : dict with str keys and list of str values (default `{}`) + By default, in Python 3.6+, the order of categorical values in axes, + legends and facets depends on the order in which these values are first + encountered in `data_frame` (and no order is guaranteed by default in + Python below 3.6). This parameter is used to force a specific ordering + of values per column. The keys of this dict should correspond to column + names, and the values should be lists of strings corresponding to the + specific display order desired. + labels : dict with str keys and str values (default `{}`) + By default, column names are used in the figure for axis titles, legend + entries and hovers. This parameter allows this to be overridden. The + keys of this dict should correspond to column names, and the values + should correspond to the desired label to be displayed. + color_discrete_sequence : list of str + Strings should define valid CSS-colors. When `color` is set and the + values in the corresponding column are not numeric, values in that + column are assigned colors by cycling through `color_discrete_sequence` + in the order described in `category_orders`, unless the value of + `color` is a key in `color_discrete_map`. Various useful color + sequences are available in the `plotly.express.colors` submodules, + specifically `plotly.express.colors.qualitative`. + color_discrete_map : dict with str keys and str values (default `{}`) + String values should define valid CSS-colors Used to override + `color_discrete_sequence` to assign a specific colors to marks + corresponding with specific values. Keys in `color_discrete_map` should + be values in the column denoted by `color`. Alternatively, if the + values of `color` are valid colors, the string `'identity'` may be + passed to cause them to be used directly. + line_dash_sequence : list of str + Strings should define valid plotly.js dash-patterns. When `line_dash` + is set, values in that column are assigned dash-patterns by cycling + through `line_dash_sequence` in the order described in + `category_orders`, unless the value of `line_dash` is a key in + `line_dash_map`. + line_dash_map : dict with str keys and str values (default `{}`) + Strings values define plotly.js dash-patterns. Used to override + `line_dash_sequences` to assign a specific dash-patterns to lines + corresponding with specific values. Keys in `line_dash_map` should be + values in the column denoted by `line_dash`. Alternatively, if the + values of `line_dash` are valid line-dash names, the string + `'identity'` may be passed to cause them to be used directly. + symbol_sequence : list of str + Strings should define valid plotly.js symbols. When `symbol` is set, + values in that column are assigned symbols by cycling through + `symbol_sequence` in the order described in `category_orders`, unless + the value of `symbol` is a key in `symbol_map`. + symbol_map : dict with str keys and str values (default `{}`) + String values should define plotly.js symbols Used to override + `symbol_sequence` to assign a specific symbols to marks corresponding + with specific values. Keys in `symbol_map` should be values in the + column denoted by `symbol`. Alternatively, if the values of `symbol` + are valid symbol names, the string `'identity'` may be passed to cause + them to be used directly. + markers : boolean (default `False`) + If `True`, markers are shown on lines. + line_shape : str (default `'linear'`) + One of `'linear'`, `'spline'`, `'hv'`, `'vh'`, `'hvh'`, or `'vhv'` + title : str + The figure title. + subtitle : str + The figure subtitle. + template : str or dict or plotly.graph_objects.layout.Template instance + The figure template name (must be a key in plotly.io.templates) or + definition. + width : int (default `None`) + The figure width in pixels. + height : int (default `None`) + The figure height in pixels. + + Returns + ------- + plotly.graph_objects.Figure """ return make_figure(args=locals(), constructor=go.Scatterternary) -line_ternary.__doc__ = make_docstring(line_ternary) - - def scatter_polar( data_frame=None, r=None, @@ -967,13 +3649,166 @@ def scatter_polar( """ In a polar scatter plot, each row of `data_frame` is represented by a symbol mark in polar coordinates. + + Parameters + ---------- + data_frame : DataFrame or array-like or dict + This argument needs to be passed for column names (and not keyword + names) to be used. Array-like and dict are transformed internally to a + pandas DataFrame. Optional: if missing, a DataFrame gets constructed + under the hood using the other arguments. + r : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + position marks along the radial axis in polar coordinates. + theta : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + position marks along the angular axis in polar coordinates. + color : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign color to marks. + symbol : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign symbols to marks. + size : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign mark sizes. + hover_name : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like appear in bold + in the hover tooltip. + hover_data : str, or list of str or int, or Series or array-like, or dict + Either a name or list of names of columns in `data_frame`, or pandas + Series, or array_like objects or a dict with column names as keys, with + values True (for default formatting) False (in order to remove this + column from hover information), or a formatting string, for example + ':.3f' or '|%a' or list-like data to appear in the hover tooltip or + tuples with a bool or formatting string as first element, and list-like + data to appear in hover as second element Values from these columns + appear as extra data in the hover tooltip. + custom_data : str, or list of str or int, or Series or array-like + Either name or list of names of columns in `data_frame`, or pandas + Series, or array_like objects Values from these columns are extra data, + to be used in widgets or Dash callbacks for example. This data is not + user-visible but is included in events emitted by the figure (lasso + selection etc.) + text : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like appear in the + figure as text labels. + animation_frame : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign marks to animation frames. + animation_group : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + provide object-constancy across animation frames: rows with matching + `animation_group`s will be treated as if they describe the same object + in each frame. + category_orders : dict with str keys and list of str values (default `{}`) + By default, in Python 3.6+, the order of categorical values in axes, + legends and facets depends on the order in which these values are first + encountered in `data_frame` (and no order is guaranteed by default in + Python below 3.6). This parameter is used to force a specific ordering + of values per column. The keys of this dict should correspond to column + names, and the values should be lists of strings corresponding to the + specific display order desired. + labels : dict with str keys and str values (default `{}`) + By default, column names are used in the figure for axis titles, legend + entries and hovers. This parameter allows this to be overridden. The + keys of this dict should correspond to column names, and the values + should correspond to the desired label to be displayed. + color_discrete_sequence : list of str + Strings should define valid CSS-colors. When `color` is set and the + values in the corresponding column are not numeric, values in that + column are assigned colors by cycling through `color_discrete_sequence` + in the order described in `category_orders`, unless the value of + `color` is a key in `color_discrete_map`. Various useful color + sequences are available in the `plotly.express.colors` submodules, + specifically `plotly.express.colors.qualitative`. + color_discrete_map : dict with str keys and str values (default `{}`) + String values should define valid CSS-colors Used to override + `color_discrete_sequence` to assign a specific colors to marks + corresponding with specific values. Keys in `color_discrete_map` should + be values in the column denoted by `color`. Alternatively, if the + values of `color` are valid colors, the string `'identity'` may be + passed to cause them to be used directly. + color_continuous_scale : list of str + Strings should define valid CSS-colors This list is used to build a + continuous color scale when the column denoted by `color` contains + numeric data. Various useful color scales are available in the + `plotly.express.colors` submodules, specifically + `plotly.express.colors.sequential`, `plotly.express.colors.diverging` + and `plotly.express.colors.cyclical`. + range_color : list of two numbers + If provided, overrides auto-scaling on the continuous color scale. + color_continuous_midpoint : number (default `None`) + If set, computes the bounds of the continuous color scale to have the + desired midpoint. Setting this value is recommended when using + `plotly.express.colors.diverging` color scales as the inputs to + `color_continuous_scale`. + symbol_sequence : list of str + Strings should define valid plotly.js symbols. When `symbol` is set, + values in that column are assigned symbols by cycling through + `symbol_sequence` in the order described in `category_orders`, unless + the value of `symbol` is a key in `symbol_map`. + symbol_map : dict with str keys and str values (default `{}`) + String values should define plotly.js symbols Used to override + `symbol_sequence` to assign a specific symbols to marks corresponding + with specific values. Keys in `symbol_map` should be values in the + column denoted by `symbol`. Alternatively, if the values of `symbol` + are valid symbol names, the string `'identity'` may be passed to cause + them to be used directly. + opacity : float + Value between 0 and 1. Sets the opacity for markers. + direction : str + One of '`counterclockwise'` or `'clockwise'`. Default is `'clockwise'` + Sets the direction in which increasing values of the angular axis are + drawn. + start_angle : int (default `90`) + Sets start angle for the angular axis, with 0 being due east and 90 + being due north. + size_max : int (default `20`) + Set the maximum mark size when using `size`. + range_r : list of two numbers + If provided, overrides auto-scaling on the radial axis in polar + coordinates. + range_theta : list of two numbers + If provided, overrides auto-scaling on the angular axis in polar + coordinates. + log_r : boolean (default `False`) + If `True`, the radial axis is log-scaled in polar coordinates. + render_mode : str + One of `'auto'`, `'svg'` or `'webgl'`, default `'auto'` Controls the + browser API used to draw marks. `'svg'` is appropriate for figures of + less than 1000 data points, and will allow for fully-vectorized output. + `'webgl'` is likely necessary for acceptable performance above 1000 + points but rasterizes part of the output. `'auto'` uses heuristics to + choose the mode. + title : str + The figure title. + subtitle : str + The figure subtitle. + template : str or dict or plotly.graph_objects.layout.Template instance + The figure template name (must be a key in plotly.io.templates) or + definition. + width : int (default `None`) + The figure width in pixels. + height : int (default `None`) + The figure height in pixels. + + Returns + ------- + plotly.graph_objects.Figure """ return make_figure(args=locals(), constructor=go.Scatterpolar) -scatter_polar.__doc__ = make_docstring(scatter_polar) - - def line_polar( data_frame=None, r=None, @@ -1014,13 +3849,172 @@ def line_polar( """ In a polar line plot, each row of `data_frame` is represented as a vertex of a polyline mark in polar coordinates. + + Parameters + ---------- + data_frame : DataFrame or array-like or dict + This argument needs to be passed for column names (and not keyword + names) to be used. Array-like and dict are transformed internally to a + pandas DataFrame. Optional: if missing, a DataFrame gets constructed + under the hood using the other arguments. + r : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + position marks along the radial axis in polar coordinates. + theta : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + position marks along the angular axis in polar coordinates. + color : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign color to marks. + line_dash : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign dash-patterns to lines. + hover_name : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like appear in bold + in the hover tooltip. + hover_data : str, or list of str or int, or Series or array-like, or dict + Either a name or list of names of columns in `data_frame`, or pandas + Series, or array_like objects or a dict with column names as keys, with + values True (for default formatting) False (in order to remove this + column from hover information), or a formatting string, for example + ':.3f' or '|%a' or list-like data to appear in the hover tooltip or + tuples with a bool or formatting string as first element, and list-like + data to appear in hover as second element Values from these columns + appear as extra data in the hover tooltip. + custom_data : str, or list of str or int, or Series or array-like + Either name or list of names of columns in `data_frame`, or pandas + Series, or array_like objects Values from these columns are extra data, + to be used in widgets or Dash callbacks for example. This data is not + user-visible but is included in events emitted by the figure (lasso + selection etc.) + line_group : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + group rows of `data_frame` into lines. + text : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like appear in the + figure as text labels. + symbol : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign symbols to marks. + animation_frame : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign marks to animation frames. + animation_group : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + provide object-constancy across animation frames: rows with matching + `animation_group`s will be treated as if they describe the same object + in each frame. + category_orders : dict with str keys and list of str values (default `{}`) + By default, in Python 3.6+, the order of categorical values in axes, + legends and facets depends on the order in which these values are first + encountered in `data_frame` (and no order is guaranteed by default in + Python below 3.6). This parameter is used to force a specific ordering + of values per column. The keys of this dict should correspond to column + names, and the values should be lists of strings corresponding to the + specific display order desired. + labels : dict with str keys and str values (default `{}`) + By default, column names are used in the figure for axis titles, legend + entries and hovers. This parameter allows this to be overridden. The + keys of this dict should correspond to column names, and the values + should correspond to the desired label to be displayed. + color_discrete_sequence : list of str + Strings should define valid CSS-colors. When `color` is set and the + values in the corresponding column are not numeric, values in that + column are assigned colors by cycling through `color_discrete_sequence` + in the order described in `category_orders`, unless the value of + `color` is a key in `color_discrete_map`. Various useful color + sequences are available in the `plotly.express.colors` submodules, + specifically `plotly.express.colors.qualitative`. + color_discrete_map : dict with str keys and str values (default `{}`) + String values should define valid CSS-colors Used to override + `color_discrete_sequence` to assign a specific colors to marks + corresponding with specific values. Keys in `color_discrete_map` should + be values in the column denoted by `color`. Alternatively, if the + values of `color` are valid colors, the string `'identity'` may be + passed to cause them to be used directly. + line_dash_sequence : list of str + Strings should define valid plotly.js dash-patterns. When `line_dash` + is set, values in that column are assigned dash-patterns by cycling + through `line_dash_sequence` in the order described in + `category_orders`, unless the value of `line_dash` is a key in + `line_dash_map`. + line_dash_map : dict with str keys and str values (default `{}`) + Strings values define plotly.js dash-patterns. Used to override + `line_dash_sequences` to assign a specific dash-patterns to lines + corresponding with specific values. Keys in `line_dash_map` should be + values in the column denoted by `line_dash`. Alternatively, if the + values of `line_dash` are valid line-dash names, the string + `'identity'` may be passed to cause them to be used directly. + symbol_sequence : list of str + Strings should define valid plotly.js symbols. When `symbol` is set, + values in that column are assigned symbols by cycling through + `symbol_sequence` in the order described in `category_orders`, unless + the value of `symbol` is a key in `symbol_map`. + symbol_map : dict with str keys and str values (default `{}`) + String values should define plotly.js symbols Used to override + `symbol_sequence` to assign a specific symbols to marks corresponding + with specific values. Keys in `symbol_map` should be values in the + column denoted by `symbol`. Alternatively, if the values of `symbol` + are valid symbol names, the string `'identity'` may be passed to cause + them to be used directly. + markers : boolean (default `False`) + If `True`, markers are shown on lines. + direction : str + One of '`counterclockwise'` or `'clockwise'`. Default is `'clockwise'` + Sets the direction in which increasing values of the angular axis are + drawn. + start_angle : int (default `90`) + Sets start angle for the angular axis, with 0 being due east and 90 + being due north. + line_close: boolean (default `False`) + If `True`, an extra line segment is drawn between the first and last + point. + line_shape : str (default `'linear'`) + One of `'linear'`, `'spline'`, `'hv'`, `'vh'`, `'hvh'`, or `'vhv'` + render_mode : str + One of `'auto'`, `'svg'` or `'webgl'`, default `'auto'` Controls the + browser API used to draw marks. `'svg'` is appropriate for figures of + less than 1000 data points, and will allow for fully-vectorized output. + `'webgl'` is likely necessary for acceptable performance above 1000 + points but rasterizes part of the output. `'auto'` uses heuristics to + choose the mode. + range_r : list of two numbers + If provided, overrides auto-scaling on the radial axis in polar + coordinates. + range_theta : list of two numbers + If provided, overrides auto-scaling on the angular axis in polar + coordinates. + log_r : boolean (default `False`) + If `True`, the radial axis is log-scaled in polar coordinates. + title : str + The figure title. + subtitle : str + The figure subtitle. + template : str or dict or plotly.graph_objects.layout.Template instance + The figure template name (must be a key in plotly.io.templates) or + definition. + width : int (default `None`) + The figure width in pixels. + height : int (default `None`) + The figure height in pixels. + + Returns + ------- + plotly.graph_objects.Figure """ return make_figure(args=locals(), constructor=go.Scatterpolar) -line_polar.__doc__ = make_docstring(line_polar) - - def bar_polar( data_frame=None, r=None, @@ -1058,6 +4052,158 @@ def bar_polar( """ In a polar bar plot, each row of `data_frame` is represented as a wedge mark in polar coordinates. + + Parameters + ---------- + data_frame : DataFrame or array-like or dict + This argument needs to be passed for column names (and not keyword + names) to be used. Array-like and dict are transformed internally to a + pandas DataFrame. Optional: if missing, a DataFrame gets constructed + under the hood using the other arguments. + r : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + position marks along the radial axis in polar coordinates. + theta : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + position marks along the angular axis in polar coordinates. + color : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign color to marks. + pattern_shape : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign pattern shapes to marks. + hover_name : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like appear in bold + in the hover tooltip. + hover_data : str, or list of str or int, or Series or array-like, or dict + Either a name or list of names of columns in `data_frame`, or pandas + Series, or array_like objects or a dict with column names as keys, with + values True (for default formatting) False (in order to remove this + column from hover information), or a formatting string, for example + ':.3f' or '|%a' or list-like data to appear in the hover tooltip or + tuples with a bool or formatting string as first element, and list-like + data to appear in hover as second element Values from these columns + appear as extra data in the hover tooltip. + custom_data : str, or list of str or int, or Series or array-like + Either name or list of names of columns in `data_frame`, or pandas + Series, or array_like objects Values from these columns are extra data, + to be used in widgets or Dash callbacks for example. This data is not + user-visible but is included in events emitted by the figure (lasso + selection etc.) + base : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + position the base of the bar. + animation_frame : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign marks to animation frames. + animation_group : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + provide object-constancy across animation frames: rows with matching + `animation_group`s will be treated as if they describe the same object + in each frame. + category_orders : dict with str keys and list of str values (default `{}`) + By default, in Python 3.6+, the order of categorical values in axes, + legends and facets depends on the order in which these values are first + encountered in `data_frame` (and no order is guaranteed by default in + Python below 3.6). This parameter is used to force a specific ordering + of values per column. The keys of this dict should correspond to column + names, and the values should be lists of strings corresponding to the + specific display order desired. + labels : dict with str keys and str values (default `{}`) + By default, column names are used in the figure for axis titles, legend + entries and hovers. This parameter allows this to be overridden. The + keys of this dict should correspond to column names, and the values + should correspond to the desired label to be displayed. + color_discrete_sequence : list of str + Strings should define valid CSS-colors. When `color` is set and the + values in the corresponding column are not numeric, values in that + column are assigned colors by cycling through `color_discrete_sequence` + in the order described in `category_orders`, unless the value of + `color` is a key in `color_discrete_map`. Various useful color + sequences are available in the `plotly.express.colors` submodules, + specifically `plotly.express.colors.qualitative`. + color_discrete_map : dict with str keys and str values (default `{}`) + String values should define valid CSS-colors Used to override + `color_discrete_sequence` to assign a specific colors to marks + corresponding with specific values. Keys in `color_discrete_map` should + be values in the column denoted by `color`. Alternatively, if the + values of `color` are valid colors, the string `'identity'` may be + passed to cause them to be used directly. + color_continuous_scale : list of str + Strings should define valid CSS-colors This list is used to build a + continuous color scale when the column denoted by `color` contains + numeric data. Various useful color scales are available in the + `plotly.express.colors` submodules, specifically + `plotly.express.colors.sequential`, `plotly.express.colors.diverging` + and `plotly.express.colors.cyclical`. + pattern_shape_sequence : list of str + Strings should define valid plotly.js patterns-shapes. When + `pattern_shape` is set, values in that column are assigned patterns- + shapes by cycling through `pattern_shape_sequence` in the order + described in `category_orders`, unless the value of `pattern_shape` is + a key in `pattern_shape_map`. + pattern_shape_map : dict with str keys and str values (default `{}`) + Strings values define plotly.js patterns-shapes. Used to override + `pattern_shape_sequences` to assign a specific patterns-shapes to lines + corresponding with specific values. Keys in `pattern_shape_map` should + be values in the column denoted by `pattern_shape`. Alternatively, if + the values of `pattern_shape` are valid patterns-shapes names, the + string `'identity'` may be passed to cause them to be used directly. + range_color : list of two numbers + If provided, overrides auto-scaling on the continuous color scale. + color_continuous_midpoint : number (default `None`) + If set, computes the bounds of the continuous color scale to have the + desired midpoint. Setting this value is recommended when using + `plotly.express.colors.diverging` color scales as the inputs to + `color_continuous_scale`. + barnorm : str (default `None`) + One of `'fraction'` or `'percent'`. If `'fraction'`, the value of each + bar is divided by the sum of all values at that location coordinate. + `'percent'` is the same but multiplied by 100 to show percentages. + `None` will stack up all values at each location coordinate. + barmode : str (default `'relative'`) + One of `'group'`, `'overlay'` or `'relative'` In `'relative'` mode, + bars are stacked above zero for positive values and below zero for + negative values. In `'overlay'` mode, bars are drawn on top of one + another. In `'group'` mode, bars are placed beside each other. + direction : str + One of '`counterclockwise'` or `'clockwise'`. Default is `'clockwise'` + Sets the direction in which increasing values of the angular axis are + drawn. + start_angle : int (default `90`) + Sets start angle for the angular axis, with 0 being due east and 90 + being due north. + range_r : list of two numbers + If provided, overrides auto-scaling on the radial axis in polar + coordinates. + range_theta : list of two numbers + If provided, overrides auto-scaling on the angular axis in polar + coordinates. + log_r : boolean (default `False`) + If `True`, the radial axis is log-scaled in polar coordinates. + title : str + The figure title. + subtitle : str + The figure subtitle. + template : str or dict or plotly.graph_objects.layout.Template instance + The figure template name (must be a key in plotly.io.templates) or + definition. + width : int (default `None`) + The figure width in pixels. + height : int (default `None`) + The figure height in pixels. + + Returns + ------- + plotly.graph_objects.Figure """ return make_figure( args=locals(), @@ -1066,9 +4212,6 @@ def bar_polar( ) -bar_polar.__doc__ = make_docstring(bar_polar) - - def choropleth( data_frame=None, lat=None, @@ -1109,6 +4252,162 @@ def choropleth( """ In a choropleth map, each row of `data_frame` is represented by a colored region mark on a map. + + Parameters + ---------- + data_frame : DataFrame or array-like or dict + This argument needs to be passed for column names (and not keyword + names) to be used. Array-like and dict are transformed internally to a + pandas DataFrame. Optional: if missing, a DataFrame gets constructed + under the hood using the other arguments. + lat : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + position marks according to latitude on a map. + lon : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + position marks according to longitude on a map. + locations : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are to be + interpreted according to `locationmode` and mapped to + longitude/latitude. + locationmode : str + One of 'ISO-3', 'USA-states', or 'country names' Determines the set of + locations used to match entries in `locations` to regions on the map. + geojson : GeoJSON-formatted dict + Must contain a Polygon feature collection, with IDs, which are + references from `locations`. + featureidkey : str (default: `'id'`) + Path to field in GeoJSON feature object with which to match the values + passed in to `locations`.The most common alternative to the default is + of the form `'properties.`. + color : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign color to marks. + facet_row : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign marks to facetted subplots in the vertical direction. + facet_col : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign marks to facetted subplots in the horizontal direction. + facet_col_wrap : int + Maximum number of facet columns. Wraps the column variable at this + width, so that the column facets span multiple rows. Ignored if 0, and + forced to 0 if `facet_row` or a `marginal` is set. + facet_row_spacing : float between 0 and 1 + Spacing between facet rows, in paper units. Default is 0.03 or 0.07 + when facet_col_wrap is used. + facet_col_spacing : float between 0 and 1 + Spacing between facet columns, in paper units Default is 0.02. + hover_name : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like appear in bold + in the hover tooltip. + hover_data : str, or list of str or int, or Series or array-like, or dict + Either a name or list of names of columns in `data_frame`, or pandas + Series, or array_like objects or a dict with column names as keys, with + values True (for default formatting) False (in order to remove this + column from hover information), or a formatting string, for example + ':.3f' or '|%a' or list-like data to appear in the hover tooltip or + tuples with a bool or formatting string as first element, and list-like + data to appear in hover as second element Values from these columns + appear as extra data in the hover tooltip. + custom_data : str, or list of str or int, or Series or array-like + Either name or list of names of columns in `data_frame`, or pandas + Series, or array_like objects Values from these columns are extra data, + to be used in widgets or Dash callbacks for example. This data is not + user-visible but is included in events emitted by the figure (lasso + selection etc.) + animation_frame : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign marks to animation frames. + animation_group : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + provide object-constancy across animation frames: rows with matching + `animation_group`s will be treated as if they describe the same object + in each frame. + category_orders : dict with str keys and list of str values (default `{}`) + By default, in Python 3.6+, the order of categorical values in axes, + legends and facets depends on the order in which these values are first + encountered in `data_frame` (and no order is guaranteed by default in + Python below 3.6). This parameter is used to force a specific ordering + of values per column. The keys of this dict should correspond to column + names, and the values should be lists of strings corresponding to the + specific display order desired. + labels : dict with str keys and str values (default `{}`) + By default, column names are used in the figure for axis titles, legend + entries and hovers. This parameter allows this to be overridden. The + keys of this dict should correspond to column names, and the values + should correspond to the desired label to be displayed. + color_discrete_sequence : list of str + Strings should define valid CSS-colors. When `color` is set and the + values in the corresponding column are not numeric, values in that + column are assigned colors by cycling through `color_discrete_sequence` + in the order described in `category_orders`, unless the value of + `color` is a key in `color_discrete_map`. Various useful color + sequences are available in the `plotly.express.colors` submodules, + specifically `plotly.express.colors.qualitative`. + color_discrete_map : dict with str keys and str values (default `{}`) + String values should define valid CSS-colors Used to override + `color_discrete_sequence` to assign a specific colors to marks + corresponding with specific values. Keys in `color_discrete_map` should + be values in the column denoted by `color`. Alternatively, if the + values of `color` are valid colors, the string `'identity'` may be + passed to cause them to be used directly. + color_continuous_scale : list of str + Strings should define valid CSS-colors This list is used to build a + continuous color scale when the column denoted by `color` contains + numeric data. Various useful color scales are available in the + `plotly.express.colors` submodules, specifically + `plotly.express.colors.sequential`, `plotly.express.colors.diverging` + and `plotly.express.colors.cyclical`. + range_color : list of two numbers + If provided, overrides auto-scaling on the continuous color scale. + color_continuous_midpoint : number (default `None`) + If set, computes the bounds of the continuous color scale to have the + desired midpoint. Setting this value is recommended when using + `plotly.express.colors.diverging` color scales as the inputs to + `color_continuous_scale`. + projection : str + One of `'equirectangular'`, `'mercator'`, `'orthographic'`, `'natural + earth'`, `'kavrayskiy7'`, `'miller'`, `'robinson'`, `'eckert4'`, + `'azimuthal equal area'`, `'azimuthal equidistant'`, `'conic equal + area'`, `'conic conformal'`, `'conic equidistant'`, `'gnomonic'`, + `'stereographic'`, `'mollweide'`, `'hammer'`, `'transverse mercator'`, + `'albers usa'`, `'winkel tripel'`, `'aitoff'`, or `'sinusoidal'`Default + depends on `scope`. + scope : str (default `'world'`). + One of `'world'`, `'usa'`, `'europe'`, `'asia'`, `'africa'`, `'north + america'`, or `'south america'`Default is `'world'` unless `projection` + is set to `'albers usa'`, which forces `'usa'`. + center : dict + Dict keys are `'lat'` and `'lon'` Sets the center point of the map. + fitbounds : str (default `False`). + One of `False`, `locations` or `geojson`. + basemap_visible : bool + Force the basemap visibility. + title : str + The figure title. + subtitle : str + The figure subtitle. + template : str or dict or plotly.graph_objects.layout.Template instance + The figure template name (must be a key in plotly.io.templates) or + definition. + width : int (default `None`) + The figure width in pixels. + height : int (default `None`) + The figure height in pixels. + + Returns + ------- + plotly.graph_objects.Figure """ return make_figure( args=locals(), @@ -1117,9 +4416,6 @@ def choropleth( ) -choropleth.__doc__ = make_docstring(choropleth) - - def scatter_geo( data_frame=None, lat=None, @@ -1167,6 +4463,190 @@ def scatter_geo( """ In a geographic scatter plot, each row of `data_frame` is represented by a symbol mark on a map. + + Parameters + ---------- + data_frame : DataFrame or array-like or dict + This argument needs to be passed for column names (and not keyword + names) to be used. Array-like and dict are transformed internally to a + pandas DataFrame. Optional: if missing, a DataFrame gets constructed + under the hood using the other arguments. + lat : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + position marks according to latitude on a map. + lon : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + position marks according to longitude on a map. + locations : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are to be + interpreted according to `locationmode` and mapped to + longitude/latitude. + locationmode : str + One of 'ISO-3', 'USA-states', or 'country names' Determines the set of + locations used to match entries in `locations` to regions on the map. + geojson : GeoJSON-formatted dict + Must contain a Polygon feature collection, with IDs, which are + references from `locations`. + featureidkey : str (default: `'id'`) + Path to field in GeoJSON feature object with which to match the values + passed in to `locations`.The most common alternative to the default is + of the form `'properties.`. + color : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign color to marks. + text : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like appear in the + figure as text labels. + symbol : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign symbols to marks. + facet_row : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign marks to facetted subplots in the vertical direction. + facet_col : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign marks to facetted subplots in the horizontal direction. + facet_col_wrap : int + Maximum number of facet columns. Wraps the column variable at this + width, so that the column facets span multiple rows. Ignored if 0, and + forced to 0 if `facet_row` or a `marginal` is set. + facet_row_spacing : float between 0 and 1 + Spacing between facet rows, in paper units. Default is 0.03 or 0.07 + when facet_col_wrap is used. + facet_col_spacing : float between 0 and 1 + Spacing between facet columns, in paper units Default is 0.02. + hover_name : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like appear in bold + in the hover tooltip. + hover_data : str, or list of str or int, or Series or array-like, or dict + Either a name or list of names of columns in `data_frame`, or pandas + Series, or array_like objects or a dict with column names as keys, with + values True (for default formatting) False (in order to remove this + column from hover information), or a formatting string, for example + ':.3f' or '|%a' or list-like data to appear in the hover tooltip or + tuples with a bool or formatting string as first element, and list-like + data to appear in hover as second element Values from these columns + appear as extra data in the hover tooltip. + custom_data : str, or list of str or int, or Series or array-like + Either name or list of names of columns in `data_frame`, or pandas + Series, or array_like objects Values from these columns are extra data, + to be used in widgets or Dash callbacks for example. This data is not + user-visible but is included in events emitted by the figure (lasso + selection etc.) + size : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign mark sizes. + animation_frame : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign marks to animation frames. + animation_group : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + provide object-constancy across animation frames: rows with matching + `animation_group`s will be treated as if they describe the same object + in each frame. + category_orders : dict with str keys and list of str values (default `{}`) + By default, in Python 3.6+, the order of categorical values in axes, + legends and facets depends on the order in which these values are first + encountered in `data_frame` (and no order is guaranteed by default in + Python below 3.6). This parameter is used to force a specific ordering + of values per column. The keys of this dict should correspond to column + names, and the values should be lists of strings corresponding to the + specific display order desired. + labels : dict with str keys and str values (default `{}`) + By default, column names are used in the figure for axis titles, legend + entries and hovers. This parameter allows this to be overridden. The + keys of this dict should correspond to column names, and the values + should correspond to the desired label to be displayed. + color_discrete_sequence : list of str + Strings should define valid CSS-colors. When `color` is set and the + values in the corresponding column are not numeric, values in that + column are assigned colors by cycling through `color_discrete_sequence` + in the order described in `category_orders`, unless the value of + `color` is a key in `color_discrete_map`. Various useful color + sequences are available in the `plotly.express.colors` submodules, + specifically `plotly.express.colors.qualitative`. + color_discrete_map : dict with str keys and str values (default `{}`) + String values should define valid CSS-colors Used to override + `color_discrete_sequence` to assign a specific colors to marks + corresponding with specific values. Keys in `color_discrete_map` should + be values in the column denoted by `color`. Alternatively, if the + values of `color` are valid colors, the string `'identity'` may be + passed to cause them to be used directly. + color_continuous_scale : list of str + Strings should define valid CSS-colors This list is used to build a + continuous color scale when the column denoted by `color` contains + numeric data. Various useful color scales are available in the + `plotly.express.colors` submodules, specifically + `plotly.express.colors.sequential`, `plotly.express.colors.diverging` + and `plotly.express.colors.cyclical`. + range_color : list of two numbers + If provided, overrides auto-scaling on the continuous color scale. + color_continuous_midpoint : number (default `None`) + If set, computes the bounds of the continuous color scale to have the + desired midpoint. Setting this value is recommended when using + `plotly.express.colors.diverging` color scales as the inputs to + `color_continuous_scale`. + symbol_sequence : list of str + Strings should define valid plotly.js symbols. When `symbol` is set, + values in that column are assigned symbols by cycling through + `symbol_sequence` in the order described in `category_orders`, unless + the value of `symbol` is a key in `symbol_map`. + symbol_map : dict with str keys and str values (default `{}`) + String values should define plotly.js symbols Used to override + `symbol_sequence` to assign a specific symbols to marks corresponding + with specific values. Keys in `symbol_map` should be values in the + column denoted by `symbol`. Alternatively, if the values of `symbol` + are valid symbol names, the string `'identity'` may be passed to cause + them to be used directly. + opacity : float + Value between 0 and 1. Sets the opacity for markers. + size_max : int (default `20`) + Set the maximum mark size when using `size`. + projection : str + One of `'equirectangular'`, `'mercator'`, `'orthographic'`, `'natural + earth'`, `'kavrayskiy7'`, `'miller'`, `'robinson'`, `'eckert4'`, + `'azimuthal equal area'`, `'azimuthal equidistant'`, `'conic equal + area'`, `'conic conformal'`, `'conic equidistant'`, `'gnomonic'`, + `'stereographic'`, `'mollweide'`, `'hammer'`, `'transverse mercator'`, + `'albers usa'`, `'winkel tripel'`, `'aitoff'`, or `'sinusoidal'`Default + depends on `scope`. + scope : str (default `'world'`). + One of `'world'`, `'usa'`, `'europe'`, `'asia'`, `'africa'`, `'north + america'`, or `'south america'`Default is `'world'` unless `projection` + is set to `'albers usa'`, which forces `'usa'`. + center : dict + Dict keys are `'lat'` and `'lon'` Sets the center point of the map. + fitbounds : str (default `False`). + One of `False`, `locations` or `geojson`. + basemap_visible : bool + Force the basemap visibility. + title : str + The figure title. + subtitle : str + The figure subtitle. + template : str or dict or plotly.graph_objects.layout.Template instance + The figure template name (must be a key in plotly.io.templates) or + definition. + width : int (default `None`) + The figure width in pixels. + height : int (default `None`) + The figure height in pixels. + + Returns + ------- + plotly.graph_objects.Figure """ return make_figure( args=locals(), @@ -1175,9 +4655,6 @@ def scatter_geo( ) -scatter_geo.__doc__ = make_docstring(scatter_geo) - - def line_geo( data_frame=None, lat=None, @@ -1224,6 +4701,191 @@ def line_geo( """ In a geographic line plot, each row of `data_frame` is represented as a vertex of a polyline mark on a map. + + Parameters + ---------- + data_frame : DataFrame or array-like or dict + This argument needs to be passed for column names (and not keyword + names) to be used. Array-like and dict are transformed internally to a + pandas DataFrame. Optional: if missing, a DataFrame gets constructed + under the hood using the other arguments. + lat : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + position marks according to latitude on a map. + lon : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + position marks according to longitude on a map. + locations : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are to be + interpreted according to `locationmode` and mapped to + longitude/latitude. + locationmode : str + One of 'ISO-3', 'USA-states', or 'country names' Determines the set of + locations used to match entries in `locations` to regions on the map. + geojson : GeoJSON-formatted dict + Must contain a Polygon feature collection, with IDs, which are + references from `locations`. + featureidkey : str (default: `'id'`) + Path to field in GeoJSON feature object with which to match the values + passed in to `locations`.The most common alternative to the default is + of the form `'properties.`. + color : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign color to marks. + line_dash : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign dash-patterns to lines. + text : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like appear in the + figure as text labels. + facet_row : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign marks to facetted subplots in the vertical direction. + facet_col : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign marks to facetted subplots in the horizontal direction. + facet_col_wrap : int + Maximum number of facet columns. Wraps the column variable at this + width, so that the column facets span multiple rows. Ignored if 0, and + forced to 0 if `facet_row` or a `marginal` is set. + facet_row_spacing : float between 0 and 1 + Spacing between facet rows, in paper units. Default is 0.03 or 0.07 + when facet_col_wrap is used. + facet_col_spacing : float between 0 and 1 + Spacing between facet columns, in paper units Default is 0.02. + hover_name : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like appear in bold + in the hover tooltip. + hover_data : str, or list of str or int, or Series or array-like, or dict + Either a name or list of names of columns in `data_frame`, or pandas + Series, or array_like objects or a dict with column names as keys, with + values True (for default formatting) False (in order to remove this + column from hover information), or a formatting string, for example + ':.3f' or '|%a' or list-like data to appear in the hover tooltip or + tuples with a bool or formatting string as first element, and list-like + data to appear in hover as second element Values from these columns + appear as extra data in the hover tooltip. + custom_data : str, or list of str or int, or Series or array-like + Either name or list of names of columns in `data_frame`, or pandas + Series, or array_like objects Values from these columns are extra data, + to be used in widgets or Dash callbacks for example. This data is not + user-visible but is included in events emitted by the figure (lasso + selection etc.) + line_group : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + group rows of `data_frame` into lines. + symbol : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign symbols to marks. + animation_frame : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign marks to animation frames. + animation_group : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + provide object-constancy across animation frames: rows with matching + `animation_group`s will be treated as if they describe the same object + in each frame. + category_orders : dict with str keys and list of str values (default `{}`) + By default, in Python 3.6+, the order of categorical values in axes, + legends and facets depends on the order in which these values are first + encountered in `data_frame` (and no order is guaranteed by default in + Python below 3.6). This parameter is used to force a specific ordering + of values per column. The keys of this dict should correspond to column + names, and the values should be lists of strings corresponding to the + specific display order desired. + labels : dict with str keys and str values (default `{}`) + By default, column names are used in the figure for axis titles, legend + entries and hovers. This parameter allows this to be overridden. The + keys of this dict should correspond to column names, and the values + should correspond to the desired label to be displayed. + color_discrete_sequence : list of str + Strings should define valid CSS-colors. When `color` is set and the + values in the corresponding column are not numeric, values in that + column are assigned colors by cycling through `color_discrete_sequence` + in the order described in `category_orders`, unless the value of + `color` is a key in `color_discrete_map`. Various useful color + sequences are available in the `plotly.express.colors` submodules, + specifically `plotly.express.colors.qualitative`. + color_discrete_map : dict with str keys and str values (default `{}`) + String values should define valid CSS-colors Used to override + `color_discrete_sequence` to assign a specific colors to marks + corresponding with specific values. Keys in `color_discrete_map` should + be values in the column denoted by `color`. Alternatively, if the + values of `color` are valid colors, the string `'identity'` may be + passed to cause them to be used directly. + line_dash_sequence : list of str + Strings should define valid plotly.js dash-patterns. When `line_dash` + is set, values in that column are assigned dash-patterns by cycling + through `line_dash_sequence` in the order described in + `category_orders`, unless the value of `line_dash` is a key in + `line_dash_map`. + line_dash_map : dict with str keys and str values (default `{}`) + Strings values define plotly.js dash-patterns. Used to override + `line_dash_sequences` to assign a specific dash-patterns to lines + corresponding with specific values. Keys in `line_dash_map` should be + values in the column denoted by `line_dash`. Alternatively, if the + values of `line_dash` are valid line-dash names, the string + `'identity'` may be passed to cause them to be used directly. + symbol_sequence : list of str + Strings should define valid plotly.js symbols. When `symbol` is set, + values in that column are assigned symbols by cycling through + `symbol_sequence` in the order described in `category_orders`, unless + the value of `symbol` is a key in `symbol_map`. + symbol_map : dict with str keys and str values (default `{}`) + String values should define plotly.js symbols Used to override + `symbol_sequence` to assign a specific symbols to marks corresponding + with specific values. Keys in `symbol_map` should be values in the + column denoted by `symbol`. Alternatively, if the values of `symbol` + are valid symbol names, the string `'identity'` may be passed to cause + them to be used directly. + markers : boolean (default `False`) + If `True`, markers are shown on lines. + projection : str + One of `'equirectangular'`, `'mercator'`, `'orthographic'`, `'natural + earth'`, `'kavrayskiy7'`, `'miller'`, `'robinson'`, `'eckert4'`, + `'azimuthal equal area'`, `'azimuthal equidistant'`, `'conic equal + area'`, `'conic conformal'`, `'conic equidistant'`, `'gnomonic'`, + `'stereographic'`, `'mollweide'`, `'hammer'`, `'transverse mercator'`, + `'albers usa'`, `'winkel tripel'`, `'aitoff'`, or `'sinusoidal'`Default + depends on `scope`. + scope : str (default `'world'`). + One of `'world'`, `'usa'`, `'europe'`, `'asia'`, `'africa'`, `'north + america'`, or `'south america'`Default is `'world'` unless `projection` + is set to `'albers usa'`, which forces `'usa'`. + center : dict + Dict keys are `'lat'` and `'lon'` Sets the center point of the map. + fitbounds : str (default `False`). + One of `False`, `locations` or `geojson`. + basemap_visible : bool + Force the basemap visibility. + title : str + The figure title. + subtitle : str + The figure subtitle. + template : str or dict or plotly.graph_objects.layout.Template instance + The figure template name (must be a key in plotly.io.templates) or + definition. + width : int (default `None`) + The figure width in pixels. + height : int (default `None`) + The figure height in pixels. + + Returns + ------- + plotly.graph_objects.Figure """ return make_figure( args=locals(), @@ -1232,9 +4894,6 @@ def line_geo( ) -line_geo.__doc__ = make_docstring(line_geo) - - def scatter_map( data_frame=None, lat=None, @@ -1268,11 +4927,137 @@ def scatter_map( """ In a scatter map, each row of `data_frame` is represented by a symbol mark on the map. - """ - return make_figure(args=locals(), constructor=go.Scattermap) + Parameters + ---------- + data_frame : DataFrame or array-like or dict + This argument needs to be passed for column names (and not keyword + names) to be used. Array-like and dict are transformed internally to a + pandas DataFrame. Optional: if missing, a DataFrame gets constructed + under the hood using the other arguments. + lat : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + position marks according to latitude on a map. + lon : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + position marks according to longitude on a map. + color : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign color to marks. + text : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like appear in the + figure as text labels. + hover_name : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like appear in bold + in the hover tooltip. + hover_data : str, or list of str or int, or Series or array-like, or dict + Either a name or list of names of columns in `data_frame`, or pandas + Series, or array_like objects or a dict with column names as keys, with + values True (for default formatting) False (in order to remove this + column from hover information), or a formatting string, for example + ':.3f' or '|%a' or list-like data to appear in the hover tooltip or + tuples with a bool or formatting string as first element, and list-like + data to appear in hover as second element Values from these columns + appear as extra data in the hover tooltip. + custom_data : str, or list of str or int, or Series or array-like + Either name or list of names of columns in `data_frame`, or pandas + Series, or array_like objects Values from these columns are extra data, + to be used in widgets or Dash callbacks for example. This data is not + user-visible but is included in events emitted by the figure (lasso + selection etc.) + size : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign mark sizes. + animation_frame : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign marks to animation frames. + animation_group : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + provide object-constancy across animation frames: rows with matching + `animation_group`s will be treated as if they describe the same object + in each frame. + category_orders : dict with str keys and list of str values (default `{}`) + By default, in Python 3.6+, the order of categorical values in axes, + legends and facets depends on the order in which these values are first + encountered in `data_frame` (and no order is guaranteed by default in + Python below 3.6). This parameter is used to force a specific ordering + of values per column. The keys of this dict should correspond to column + names, and the values should be lists of strings corresponding to the + specific display order desired. + labels : dict with str keys and str values (default `{}`) + By default, column names are used in the figure for axis titles, legend + entries and hovers. This parameter allows this to be overridden. The + keys of this dict should correspond to column names, and the values + should correspond to the desired label to be displayed. + color_discrete_sequence : list of str + Strings should define valid CSS-colors. When `color` is set and the + values in the corresponding column are not numeric, values in that + column are assigned colors by cycling through `color_discrete_sequence` + in the order described in `category_orders`, unless the value of + `color` is a key in `color_discrete_map`. Various useful color + sequences are available in the `plotly.express.colors` submodules, + specifically `plotly.express.colors.qualitative`. + color_discrete_map : dict with str keys and str values (default `{}`) + String values should define valid CSS-colors Used to override + `color_discrete_sequence` to assign a specific colors to marks + corresponding with specific values. Keys in `color_discrete_map` should + be values in the column denoted by `color`. Alternatively, if the + values of `color` are valid colors, the string `'identity'` may be + passed to cause them to be used directly. + color_continuous_scale : list of str + Strings should define valid CSS-colors This list is used to build a + continuous color scale when the column denoted by `color` contains + numeric data. Various useful color scales are available in the + `plotly.express.colors` submodules, specifically + `plotly.express.colors.sequential`, `plotly.express.colors.diverging` + and `plotly.express.colors.cyclical`. + range_color : list of two numbers + If provided, overrides auto-scaling on the continuous color scale. + color_continuous_midpoint : number (default `None`) + If set, computes the bounds of the continuous color scale to have the + desired midpoint. Setting this value is recommended when using + `plotly.express.colors.diverging` color scales as the inputs to + `color_continuous_scale`. + opacity : float + Value between 0 and 1. Sets the opacity for markers. + size_max : int (default `20`) + Set the maximum mark size when using `size`. + zoom : int (default `8`) + Between 0 and 20. Sets map zoom level. + center : dict + Dict keys are `'lat'` and `'lon'` Sets the center point of the map. + map_style : str (default `'basic'`) + Identifier of base map style. Allowed values are `'basic'`, `'carto- + darkmatter'`, `'carto-darkmatter-nolabels'`, `'carto-positron'`, + `'carto-positron-nolabels'`, `'carto-voyager'`, `'carto-voyager- + nolabels'`, `'dark'`, `'light'`, `'open-street-map'`, `'outdoors'`, + `'satellite'`, `'satellite-streets'`, `'streets'`, `'white-bg'`. + title : str + The figure title. + subtitle : str + The figure subtitle. + template : str or dict or plotly.graph_objects.layout.Template instance + The figure template name (must be a key in plotly.io.templates) or + definition. + width : int (default `None`) + The figure width in pixels. + height : int (default `None`) + The figure height in pixels. + + Returns + ------- + plotly.graph_objects.Figure -scatter_map.__doc__ = make_docstring(scatter_map) + """ + return make_figure(args=locals(), constructor=go.Scattermap) def choropleth_map( @@ -1306,13 +5091,132 @@ def choropleth_map( """ In a choropleth map, each row of `data_frame` is represented by a colored region on the map. + + Parameters + ---------- + data_frame : DataFrame or array-like or dict + This argument needs to be passed for column names (and not keyword + names) to be used. Array-like and dict are transformed internally to a + pandas DataFrame. Optional: if missing, a DataFrame gets constructed + under the hood using the other arguments. + geojson : GeoJSON-formatted dict + Must contain a Polygon feature collection, with IDs, which are + references from `locations`. + featureidkey : str (default: `'id'`) + Path to field in GeoJSON feature object with which to match the values + passed in to `locations`.The most common alternative to the default is + of the form `'properties.`. + locations : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are to be + interpreted according to `locationmode` and mapped to + longitude/latitude. + color : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign color to marks. + hover_name : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like appear in bold + in the hover tooltip. + hover_data : str, or list of str or int, or Series or array-like, or dict + Either a name or list of names of columns in `data_frame`, or pandas + Series, or array_like objects or a dict with column names as keys, with + values True (for default formatting) False (in order to remove this + column from hover information), or a formatting string, for example + ':.3f' or '|%a' or list-like data to appear in the hover tooltip or + tuples with a bool or formatting string as first element, and list-like + data to appear in hover as second element Values from these columns + appear as extra data in the hover tooltip. + custom_data : str, or list of str or int, or Series or array-like + Either name or list of names of columns in `data_frame`, or pandas + Series, or array_like objects Values from these columns are extra data, + to be used in widgets or Dash callbacks for example. This data is not + user-visible but is included in events emitted by the figure (lasso + selection etc.) + animation_frame : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign marks to animation frames. + animation_group : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + provide object-constancy across animation frames: rows with matching + `animation_group`s will be treated as if they describe the same object + in each frame. + category_orders : dict with str keys and list of str values (default `{}`) + By default, in Python 3.6+, the order of categorical values in axes, + legends and facets depends on the order in which these values are first + encountered in `data_frame` (and no order is guaranteed by default in + Python below 3.6). This parameter is used to force a specific ordering + of values per column. The keys of this dict should correspond to column + names, and the values should be lists of strings corresponding to the + specific display order desired. + labels : dict with str keys and str values (default `{}`) + By default, column names are used in the figure for axis titles, legend + entries and hovers. This parameter allows this to be overridden. The + keys of this dict should correspond to column names, and the values + should correspond to the desired label to be displayed. + color_discrete_sequence : list of str + Strings should define valid CSS-colors. When `color` is set and the + values in the corresponding column are not numeric, values in that + column are assigned colors by cycling through `color_discrete_sequence` + in the order described in `category_orders`, unless the value of + `color` is a key in `color_discrete_map`. Various useful color + sequences are available in the `plotly.express.colors` submodules, + specifically `plotly.express.colors.qualitative`. + color_discrete_map : dict with str keys and str values (default `{}`) + String values should define valid CSS-colors Used to override + `color_discrete_sequence` to assign a specific colors to marks + corresponding with specific values. Keys in `color_discrete_map` should + be values in the column denoted by `color`. Alternatively, if the + values of `color` are valid colors, the string `'identity'` may be + passed to cause them to be used directly. + color_continuous_scale : list of str + Strings should define valid CSS-colors This list is used to build a + continuous color scale when the column denoted by `color` contains + numeric data. Various useful color scales are available in the + `plotly.express.colors` submodules, specifically + `plotly.express.colors.sequential`, `plotly.express.colors.diverging` + and `plotly.express.colors.cyclical`. + range_color : list of two numbers + If provided, overrides auto-scaling on the continuous color scale. + color_continuous_midpoint : number (default `None`) + If set, computes the bounds of the continuous color scale to have the + desired midpoint. Setting this value is recommended when using + `plotly.express.colors.diverging` color scales as the inputs to + `color_continuous_scale`. + opacity : float + Value between 0 and 1. Sets the opacity for markers. + zoom : int (default `8`) + Between 0 and 20. Sets map zoom level. + center : dict + Dict keys are `'lat'` and `'lon'` Sets the center point of the map. + map_style : str (default `'basic'`) + Identifier of base map style. Allowed values are `'basic'`, `'carto- + darkmatter'`, `'carto-darkmatter-nolabels'`, `'carto-positron'`, + `'carto-positron-nolabels'`, `'carto-voyager'`, `'carto-voyager- + nolabels'`, `'dark'`, `'light'`, `'open-street-map'`, `'outdoors'`, + `'satellite'`, `'satellite-streets'`, `'streets'`, `'white-bg'`. + title : str + The figure title. + subtitle : str + The figure subtitle. + template : str or dict or plotly.graph_objects.layout.Template instance + The figure template name (must be a key in plotly.io.templates) or + definition. + width : int (default `None`) + The figure width in pixels. + height : int (default `None`) + The figure height in pixels. + + Returns + ------- + plotly.graph_objects.Figure """ return make_figure(args=locals(), constructor=go.Choroplethmap) -choropleth_map.__doc__ = make_docstring(choropleth_map) - - def density_map( data_frame=None, lat=None, @@ -1342,15 +5246,117 @@ def density_map( """ In a density map, each row of `data_frame` contributes to the intensity of the color of the region around the corresponding point on the map. + + Parameters + ---------- + data_frame : DataFrame or array-like or dict + This argument needs to be passed for column names (and not keyword + names) to be used. Array-like and dict are transformed internally to a + pandas DataFrame. Optional: if missing, a DataFrame gets constructed + under the hood using the other arguments. + lat : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + position marks according to latitude on a map. + lon : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + position marks according to longitude on a map. + z : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + position marks along the z axis in cartesian coordinates. + hover_name : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like appear in bold + in the hover tooltip. + hover_data : str, or list of str or int, or Series or array-like, or dict + Either a name or list of names of columns in `data_frame`, or pandas + Series, or array_like objects or a dict with column names as keys, with + values True (for default formatting) False (in order to remove this + column from hover information), or a formatting string, for example + ':.3f' or '|%a' or list-like data to appear in the hover tooltip or + tuples with a bool or formatting string as first element, and list-like + data to appear in hover as second element Values from these columns + appear as extra data in the hover tooltip. + custom_data : str, or list of str or int, or Series or array-like + Either name or list of names of columns in `data_frame`, or pandas + Series, or array_like objects Values from these columns are extra data, + to be used in widgets or Dash callbacks for example. This data is not + user-visible but is included in events emitted by the figure (lasso + selection etc.) + animation_frame : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign marks to animation frames. + animation_group : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + provide object-constancy across animation frames: rows with matching + `animation_group`s will be treated as if they describe the same object + in each frame. + category_orders : dict with str keys and list of str values (default `{}`) + By default, in Python 3.6+, the order of categorical values in axes, + legends and facets depends on the order in which these values are first + encountered in `data_frame` (and no order is guaranteed by default in + Python below 3.6). This parameter is used to force a specific ordering + of values per column. The keys of this dict should correspond to column + names, and the values should be lists of strings corresponding to the + specific display order desired. + labels : dict with str keys and str values (default `{}`) + By default, column names are used in the figure for axis titles, legend + entries and hovers. This parameter allows this to be overridden. The + keys of this dict should correspond to column names, and the values + should correspond to the desired label to be displayed. + color_continuous_scale : list of str + Strings should define valid CSS-colors This list is used to build a + continuous color scale when the column denoted by `color` contains + numeric data. Various useful color scales are available in the + `plotly.express.colors` submodules, specifically + `plotly.express.colors.sequential`, `plotly.express.colors.diverging` + and `plotly.express.colors.cyclical`. + range_color : list of two numbers + If provided, overrides auto-scaling on the continuous color scale. + color_continuous_midpoint : number (default `None`) + If set, computes the bounds of the continuous color scale to have the + desired midpoint. Setting this value is recommended when using + `plotly.express.colors.diverging` color scales as the inputs to + `color_continuous_scale`. + opacity : float + Value between 0 and 1. Sets the opacity for markers. + zoom : int (default `8`) + Between 0 and 20. Sets map zoom level. + center : dict + Dict keys are `'lat'` and `'lon'` Sets the center point of the map. + map_style : str (default `'basic'`) + Identifier of base map style. Allowed values are `'basic'`, `'carto- + darkmatter'`, `'carto-darkmatter-nolabels'`, `'carto-positron'`, + `'carto-positron-nolabels'`, `'carto-voyager'`, `'carto-voyager- + nolabels'`, `'dark'`, `'light'`, `'open-street-map'`, `'outdoors'`, + `'satellite'`, `'satellite-streets'`, `'streets'`, `'white-bg'`. + radius : int (default is 30) + Sets the radius of influence of each point. + title : str + The figure title. + subtitle : str + The figure subtitle. + template : str or dict or plotly.graph_objects.layout.Template instance + The figure template name (must be a key in plotly.io.templates) or + definition. + width : int (default `None`) + The figure width in pixels. + height : int (default `None`) + The figure height in pixels. + + Returns + ------- + plotly.graph_objects.Figure """ return make_figure( args=locals(), constructor=go.Densitymap, trace_patch=dict(radius=radius) ) -density_map.__doc__ = make_docstring(density_map) - - def line_map( data_frame=None, lat=None, @@ -1379,13 +5385,120 @@ def line_map( """ In a line map, each row of `data_frame` is represented as a vertex of a polyline mark on the map. + + Parameters + ---------- + data_frame : DataFrame or array-like or dict + This argument needs to be passed for column names (and not keyword + names) to be used. Array-like and dict are transformed internally to a + pandas DataFrame. Optional: if missing, a DataFrame gets constructed + under the hood using the other arguments. + lat : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + position marks according to latitude on a map. + lon : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + position marks according to longitude on a map. + color : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign color to marks. + text : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like appear in the + figure as text labels. + hover_name : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like appear in bold + in the hover tooltip. + hover_data : str, or list of str or int, or Series or array-like, or dict + Either a name or list of names of columns in `data_frame`, or pandas + Series, or array_like objects or a dict with column names as keys, with + values True (for default formatting) False (in order to remove this + column from hover information), or a formatting string, for example + ':.3f' or '|%a' or list-like data to appear in the hover tooltip or + tuples with a bool or formatting string as first element, and list-like + data to appear in hover as second element Values from these columns + appear as extra data in the hover tooltip. + custom_data : str, or list of str or int, or Series or array-like + Either name or list of names of columns in `data_frame`, or pandas + Series, or array_like objects Values from these columns are extra data, + to be used in widgets or Dash callbacks for example. This data is not + user-visible but is included in events emitted by the figure (lasso + selection etc.) + line_group : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + group rows of `data_frame` into lines. + animation_frame : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign marks to animation frames. + animation_group : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + provide object-constancy across animation frames: rows with matching + `animation_group`s will be treated as if they describe the same object + in each frame. + category_orders : dict with str keys and list of str values (default `{}`) + By default, in Python 3.6+, the order of categorical values in axes, + legends and facets depends on the order in which these values are first + encountered in `data_frame` (and no order is guaranteed by default in + Python below 3.6). This parameter is used to force a specific ordering + of values per column. The keys of this dict should correspond to column + names, and the values should be lists of strings corresponding to the + specific display order desired. + labels : dict with str keys and str values (default `{}`) + By default, column names are used in the figure for axis titles, legend + entries and hovers. This parameter allows this to be overridden. The + keys of this dict should correspond to column names, and the values + should correspond to the desired label to be displayed. + color_discrete_sequence : list of str + Strings should define valid CSS-colors. When `color` is set and the + values in the corresponding column are not numeric, values in that + column are assigned colors by cycling through `color_discrete_sequence` + in the order described in `category_orders`, unless the value of + `color` is a key in `color_discrete_map`. Various useful color + sequences are available in the `plotly.express.colors` submodules, + specifically `plotly.express.colors.qualitative`. + color_discrete_map : dict with str keys and str values (default `{}`) + String values should define valid CSS-colors Used to override + `color_discrete_sequence` to assign a specific colors to marks + corresponding with specific values. Keys in `color_discrete_map` should + be values in the column denoted by `color`. Alternatively, if the + values of `color` are valid colors, the string `'identity'` may be + passed to cause them to be used directly. + zoom : int (default `8`) + Between 0 and 20. Sets map zoom level. + center : dict + Dict keys are `'lat'` and `'lon'` Sets the center point of the map. + map_style : str (default `'basic'`) + Identifier of base map style. Allowed values are `'basic'`, `'carto- + darkmatter'`, `'carto-darkmatter-nolabels'`, `'carto-positron'`, + `'carto-positron-nolabels'`, `'carto-voyager'`, `'carto-voyager- + nolabels'`, `'dark'`, `'light'`, `'open-street-map'`, `'outdoors'`, + `'satellite'`, `'satellite-streets'`, `'streets'`, `'white-bg'`. + title : str + The figure title. + subtitle : str + The figure subtitle. + template : str or dict or plotly.graph_objects.layout.Template instance + The figure template name (must be a key in plotly.io.templates) or + definition. + width : int (default `None`) + The figure width in pixels. + height : int (default `None`) + The figure height in pixels. + + Returns + ------- + plotly.graph_objects.Figure """ return make_figure(args=locals(), constructor=go.Scattermap) -line_map.__doc__ = make_docstring(line_map) - - def scatter_mapbox( data_frame=None, lat=None, @@ -1421,6 +5534,138 @@ def scatter_mapbox( Learn more at: https://plotly.com/python/mapbox-to-maplibre/ In a Mapbox scatter plot, each row of `data_frame` is represented by a symbol mark on a Mapbox map. + + Parameters + ---------- + data_frame : DataFrame or array-like or dict + This argument needs to be passed for column names (and not keyword + names) to be used. Array-like and dict are transformed internally to a + pandas DataFrame. Optional: if missing, a DataFrame gets constructed + under the hood using the other arguments. + lat : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + position marks according to latitude on a map. + lon : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + position marks according to longitude on a map. + color : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign color to marks. + text : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like appear in the + figure as text labels. + hover_name : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like appear in bold + in the hover tooltip. + hover_data : str, or list of str or int, or Series or array-like, or dict + Either a name or list of names of columns in `data_frame`, or pandas + Series, or array_like objects or a dict with column names as keys, with + values True (for default formatting) False (in order to remove this + column from hover information), or a formatting string, for example + ':.3f' or '|%a' or list-like data to appear in the hover tooltip or + tuples with a bool or formatting string as first element, and list-like + data to appear in hover as second element Values from these columns + appear as extra data in the hover tooltip. + custom_data : str, or list of str or int, or Series or array-like + Either name or list of names of columns in `data_frame`, or pandas + Series, or array_like objects Values from these columns are extra data, + to be used in widgets or Dash callbacks for example. This data is not + user-visible but is included in events emitted by the figure (lasso + selection etc.) + size : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign mark sizes. + animation_frame : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign marks to animation frames. + animation_group : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + provide object-constancy across animation frames: rows with matching + `animation_group`s will be treated as if they describe the same object + in each frame. + category_orders : dict with str keys and list of str values (default `{}`) + By default, in Python 3.6+, the order of categorical values in axes, + legends and facets depends on the order in which these values are first + encountered in `data_frame` (and no order is guaranteed by default in + Python below 3.6). This parameter is used to force a specific ordering + of values per column. The keys of this dict should correspond to column + names, and the values should be lists of strings corresponding to the + specific display order desired. + labels : dict with str keys and str values (default `{}`) + By default, column names are used in the figure for axis titles, legend + entries and hovers. This parameter allows this to be overridden. The + keys of this dict should correspond to column names, and the values + should correspond to the desired label to be displayed. + color_discrete_sequence : list of str + Strings should define valid CSS-colors. When `color` is set and the + values in the corresponding column are not numeric, values in that + column are assigned colors by cycling through `color_discrete_sequence` + in the order described in `category_orders`, unless the value of + `color` is a key in `color_discrete_map`. Various useful color + sequences are available in the `plotly.express.colors` submodules, + specifically `plotly.express.colors.qualitative`. + color_discrete_map : dict with str keys and str values (default `{}`) + String values should define valid CSS-colors Used to override + `color_discrete_sequence` to assign a specific colors to marks + corresponding with specific values. Keys in `color_discrete_map` should + be values in the column denoted by `color`. Alternatively, if the + values of `color` are valid colors, the string `'identity'` may be + passed to cause them to be used directly. + color_continuous_scale : list of str + Strings should define valid CSS-colors This list is used to build a + continuous color scale when the column denoted by `color` contains + numeric data. Various useful color scales are available in the + `plotly.express.colors` submodules, specifically + `plotly.express.colors.sequential`, `plotly.express.colors.diverging` + and `plotly.express.colors.cyclical`. + range_color : list of two numbers + If provided, overrides auto-scaling on the continuous color scale. + color_continuous_midpoint : number (default `None`) + If set, computes the bounds of the continuous color scale to have the + desired midpoint. Setting this value is recommended when using + `plotly.express.colors.diverging` color scales as the inputs to + `color_continuous_scale`. + opacity : float + Value between 0 and 1. Sets the opacity for markers. + size_max : int (default `20`) + Set the maximum mark size when using `size`. + zoom : int (default `8`) + Between 0 and 20. Sets map zoom level. + center : dict + Dict keys are `'lat'` and `'lon'` Sets the center point of the map. + mapbox_style : str (default `'basic'`, needs Mapbox API token) + Identifier of base map style, some of which require a Mapbox or Stadia + Maps API token to be set using + `plotly.express.set_mapbox_access_token()`. Allowed values which do not + require a token are `'open-street-map'`, `'white-bg'`, `'carto- + positron'`, `'carto-darkmatter'`. Allowed values which require a Mapbox + API token are `'basic'`, `'streets'`, `'outdoors'`, `'light'`, + `'dark'`, `'satellite'`, `'satellite-streets'`. Allowed values which + require a Stadia Maps API token are `'stamen-terrain'`, `'stamen- + toner'`, `'stamen-watercolor'`. + title : str + The figure title. + subtitle : str + The figure subtitle. + template : str or dict or plotly.graph_objects.layout.Template instance + The figure template name (must be a key in plotly.io.templates) or + definition. + width : int (default `None`) + The figure width in pixels. + height : int (default `None`) + The figure height in pixels. + + Returns + ------- + plotly.graph_objects.Figure """ warn( "*scatter_mapbox* is deprecated!" @@ -1432,9 +5677,6 @@ def scatter_mapbox( return make_figure(args=locals(), constructor=go.Scattermapbox) -scatter_mapbox.__doc__ = make_docstring(scatter_mapbox) - - def choropleth_mapbox( data_frame=None, geojson=None, @@ -1468,6 +5710,132 @@ def choropleth_mapbox( Learn more at: https://plotly.com/python/mapbox-to-maplibre/ In a Mapbox choropleth map, each row of `data_frame` is represented by a colored region on a Mapbox map. + + Parameters + ---------- + data_frame : DataFrame or array-like or dict + This argument needs to be passed for column names (and not keyword + names) to be used. Array-like and dict are transformed internally to a + pandas DataFrame. Optional: if missing, a DataFrame gets constructed + under the hood using the other arguments. + geojson : GeoJSON-formatted dict + Must contain a Polygon feature collection, with IDs, which are + references from `locations`. + featureidkey : str (default: `'id'`) + Path to field in GeoJSON feature object with which to match the values + passed in to `locations`.The most common alternative to the default is + of the form `'properties.`. + locations : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are to be + interpreted according to `locationmode` and mapped to + longitude/latitude. + color : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign color to marks. + hover_name : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like appear in bold + in the hover tooltip. + hover_data : str, or list of str or int, or Series or array-like, or dict + Either a name or list of names of columns in `data_frame`, or pandas + Series, or array_like objects or a dict with column names as keys, with + values True (for default formatting) False (in order to remove this + column from hover information), or a formatting string, for example + ':.3f' or '|%a' or list-like data to appear in the hover tooltip or + tuples with a bool or formatting string as first element, and list-like + data to appear in hover as second element Values from these columns + appear as extra data in the hover tooltip. + custom_data : str, or list of str or int, or Series or array-like + Either name or list of names of columns in `data_frame`, or pandas + Series, or array_like objects Values from these columns are extra data, + to be used in widgets or Dash callbacks for example. This data is not + user-visible but is included in events emitted by the figure (lasso + selection etc.) + animation_frame : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign marks to animation frames. + animation_group : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + provide object-constancy across animation frames: rows with matching + `animation_group`s will be treated as if they describe the same object + in each frame. + category_orders : dict with str keys and list of str values (default `{}`) + By default, in Python 3.6+, the order of categorical values in axes, + legends and facets depends on the order in which these values are first + encountered in `data_frame` (and no order is guaranteed by default in + Python below 3.6). This parameter is used to force a specific ordering + of values per column. The keys of this dict should correspond to column + names, and the values should be lists of strings corresponding to the + specific display order desired. + labels : dict with str keys and str values (default `{}`) + By default, column names are used in the figure for axis titles, legend + entries and hovers. This parameter allows this to be overridden. The + keys of this dict should correspond to column names, and the values + should correspond to the desired label to be displayed. + color_discrete_sequence : list of str + Strings should define valid CSS-colors. When `color` is set and the + values in the corresponding column are not numeric, values in that + column are assigned colors by cycling through `color_discrete_sequence` + in the order described in `category_orders`, unless the value of + `color` is a key in `color_discrete_map`. Various useful color + sequences are available in the `plotly.express.colors` submodules, + specifically `plotly.express.colors.qualitative`. + color_discrete_map : dict with str keys and str values (default `{}`) + String values should define valid CSS-colors Used to override + `color_discrete_sequence` to assign a specific colors to marks + corresponding with specific values. Keys in `color_discrete_map` should + be values in the column denoted by `color`. Alternatively, if the + values of `color` are valid colors, the string `'identity'` may be + passed to cause them to be used directly. + color_continuous_scale : list of str + Strings should define valid CSS-colors This list is used to build a + continuous color scale when the column denoted by `color` contains + numeric data. Various useful color scales are available in the + `plotly.express.colors` submodules, specifically + `plotly.express.colors.sequential`, `plotly.express.colors.diverging` + and `plotly.express.colors.cyclical`. + range_color : list of two numbers + If provided, overrides auto-scaling on the continuous color scale. + color_continuous_midpoint : number (default `None`) + If set, computes the bounds of the continuous color scale to have the + desired midpoint. Setting this value is recommended when using + `plotly.express.colors.diverging` color scales as the inputs to + `color_continuous_scale`. + opacity : float + Value between 0 and 1. Sets the opacity for markers. + zoom : int (default `8`) + Between 0 and 20. Sets map zoom level. + center : dict + Dict keys are `'lat'` and `'lon'` Sets the center point of the map. + mapbox_style : str (default `'basic'`, needs Mapbox API token) + Identifier of base map style, some of which require a Mapbox or Stadia + Maps API token to be set using + `plotly.express.set_mapbox_access_token()`. Allowed values which do not + require a token are `'open-street-map'`, `'white-bg'`, `'carto- + positron'`, `'carto-darkmatter'`. Allowed values which require a Mapbox + API token are `'basic'`, `'streets'`, `'outdoors'`, `'light'`, + `'dark'`, `'satellite'`, `'satellite-streets'`. Allowed values which + require a Stadia Maps API token are `'stamen-terrain'`, `'stamen- + toner'`, `'stamen-watercolor'`. + title : str + The figure title. + subtitle : str + The figure subtitle. + template : str or dict or plotly.graph_objects.layout.Template instance + The figure template name (must be a key in plotly.io.templates) or + definition. + width : int (default `None`) + The figure width in pixels. + height : int (default `None`) + The figure height in pixels. + + Returns + ------- + plotly.graph_objects.Figure """ warn( "*choropleth_mapbox* is deprecated!" @@ -1479,9 +5847,6 @@ def choropleth_mapbox( return make_figure(args=locals(), constructor=go.Choroplethmapbox) -choropleth_mapbox.__doc__ = make_docstring(choropleth_mapbox) - - def density_mapbox( data_frame=None, lat=None, @@ -1513,6 +5878,115 @@ def density_mapbox( Learn more at: https://plotly.com/python/mapbox-to-maplibre/ In a Mapbox density map, each row of `data_frame` contributes to the intensity of the color of the region around the corresponding point on the map + + Parameters + ---------- + data_frame : DataFrame or array-like or dict + This argument needs to be passed for column names (and not keyword + names) to be used. Array-like and dict are transformed internally to a + pandas DataFrame. Optional: if missing, a DataFrame gets constructed + under the hood using the other arguments. + lat : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + position marks according to latitude on a map. + lon : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + position marks according to longitude on a map. + z : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + position marks along the z axis in cartesian coordinates. + hover_name : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like appear in bold + in the hover tooltip. + hover_data : str, or list of str or int, or Series or array-like, or dict + Either a name or list of names of columns in `data_frame`, or pandas + Series, or array_like objects or a dict with column names as keys, with + values True (for default formatting) False (in order to remove this + column from hover information), or a formatting string, for example + ':.3f' or '|%a' or list-like data to appear in the hover tooltip or + tuples with a bool or formatting string as first element, and list-like + data to appear in hover as second element Values from these columns + appear as extra data in the hover tooltip. + custom_data : str, or list of str or int, or Series or array-like + Either name or list of names of columns in `data_frame`, or pandas + Series, or array_like objects Values from these columns are extra data, + to be used in widgets or Dash callbacks for example. This data is not + user-visible but is included in events emitted by the figure (lasso + selection etc.) + animation_frame : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign marks to animation frames. + animation_group : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + provide object-constancy across animation frames: rows with matching + `animation_group`s will be treated as if they describe the same object + in each frame. + category_orders : dict with str keys and list of str values (default `{}`) + By default, in Python 3.6+, the order of categorical values in axes, + legends and facets depends on the order in which these values are first + encountered in `data_frame` (and no order is guaranteed by default in + Python below 3.6). This parameter is used to force a specific ordering + of values per column. The keys of this dict should correspond to column + names, and the values should be lists of strings corresponding to the + specific display order desired. + labels : dict with str keys and str values (default `{}`) + By default, column names are used in the figure for axis titles, legend + entries and hovers. This parameter allows this to be overridden. The + keys of this dict should correspond to column names, and the values + should correspond to the desired label to be displayed. + color_continuous_scale : list of str + Strings should define valid CSS-colors This list is used to build a + continuous color scale when the column denoted by `color` contains + numeric data. Various useful color scales are available in the + `plotly.express.colors` submodules, specifically + `plotly.express.colors.sequential`, `plotly.express.colors.diverging` + and `plotly.express.colors.cyclical`. + range_color : list of two numbers + If provided, overrides auto-scaling on the continuous color scale. + color_continuous_midpoint : number (default `None`) + If set, computes the bounds of the continuous color scale to have the + desired midpoint. Setting this value is recommended when using + `plotly.express.colors.diverging` color scales as the inputs to + `color_continuous_scale`. + opacity : float + Value between 0 and 1. Sets the opacity for markers. + zoom : int (default `8`) + Between 0 and 20. Sets map zoom level. + center : dict + Dict keys are `'lat'` and `'lon'` Sets the center point of the map. + mapbox_style : str (default `'basic'`, needs Mapbox API token) + Identifier of base map style, some of which require a Mapbox or Stadia + Maps API token to be set using + `plotly.express.set_mapbox_access_token()`. Allowed values which do not + require a token are `'open-street-map'`, `'white-bg'`, `'carto- + positron'`, `'carto-darkmatter'`. Allowed values which require a Mapbox + API token are `'basic'`, `'streets'`, `'outdoors'`, `'light'`, + `'dark'`, `'satellite'`, `'satellite-streets'`. Allowed values which + require a Stadia Maps API token are `'stamen-terrain'`, `'stamen- + toner'`, `'stamen-watercolor'`. + radius : int (default is 30) + Sets the radius of influence of each point. + title : str + The figure title. + subtitle : str + The figure subtitle. + template : str or dict or plotly.graph_objects.layout.Template instance + The figure template name (must be a key in plotly.io.templates) or + definition. + width : int (default `None`) + The figure width in pixels. + height : int (default `None`) + The figure height in pixels. + + Returns + ------- + plotly.graph_objects.Figure """ warn( "*density_mapbox* is deprecated!" @@ -1526,9 +6000,6 @@ def density_mapbox( ) -density_mapbox.__doc__ = make_docstring(density_mapbox) - - def line_mapbox( data_frame=None, lat=None, @@ -1559,6 +6030,121 @@ def line_mapbox( Learn more at: https://plotly.com/python/mapbox-to-maplibre/ In a Mapbox line plot, each row of `data_frame` is represented as a vertex of a polyline mark on a Mapbox map. + + + Parameters + ---------- + data_frame : DataFrame or array-like or dict + This argument needs to be passed for column names (and not keyword + names) to be used. Array-like and dict are transformed internally to a + pandas DataFrame. Optional: if missing, a DataFrame gets constructed + under the hood using the other arguments. + lat : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + position marks according to latitude on a map. + lon : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + position marks according to longitude on a map. + color : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign color to marks. + text : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like appear in the + figure as text labels. + hover_name : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like appear in bold + in the hover tooltip. + hover_data : str, or list of str or int, or Series or array-like, or dict + Either a name or list of names of columns in `data_frame`, or pandas + Series, or array_like objects or a dict with column names as keys, with + values True (for default formatting) False (in order to remove this + column from hover information), or a formatting string, for example + ':.3f' or '|%a' or list-like data to appear in the hover tooltip or + tuples with a bool or formatting string as first element, and list-like + data to appear in hover as second element Values from these columns + appear as extra data in the hover tooltip. + custom_data : str, or list of str or int, or Series or array-like + Either name or list of names of columns in `data_frame`, or pandas + Series, or array_like objects Values from these columns are extra data, + to be used in widgets or Dash callbacks for example. This data is not + user-visible but is included in events emitted by the figure (lasso + selection etc.) + line_group : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + group rows of `data_frame` into lines. + animation_frame : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign marks to animation frames. + animation_group : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + provide object-constancy across animation frames: rows with matching + `animation_group`s will be treated as if they describe the same object + in each frame. + category_orders : dict with str keys and list of str values (default `{}`) + By default, in Python 3.6+, the order of categorical values in axes, + legends and facets depends on the order in which these values are first + encountered in `data_frame` (and no order is guaranteed by default in + Python below 3.6). This parameter is used to force a specific ordering + of values per column. The keys of this dict should correspond to column + names, and the values should be lists of strings corresponding to the + specific display order desired. + labels : dict with str keys and str values (default `{}`) + By default, column names are used in the figure for axis titles, legend + entries and hovers. This parameter allows this to be overridden. The + keys of this dict should correspond to column names, and the values + should correspond to the desired label to be displayed. + color_discrete_sequence : list of str + Strings should define valid CSS-colors. When `color` is set and the + values in the corresponding column are not numeric, values in that + column are assigned colors by cycling through `color_discrete_sequence` + in the order described in `category_orders`, unless the value of + `color` is a key in `color_discrete_map`. Various useful color + sequences are available in the `plotly.express.colors` submodules, + specifically `plotly.express.colors.qualitative`. + color_discrete_map : dict with str keys and str values (default `{}`) + String values should define valid CSS-colors Used to override + `color_discrete_sequence` to assign a specific colors to marks + corresponding with specific values. Keys in `color_discrete_map` should + be values in the column denoted by `color`. Alternatively, if the + values of `color` are valid colors, the string `'identity'` may be + passed to cause them to be used directly. + zoom : int (default `8`) + Between 0 and 20. Sets map zoom level. + center : dict + Dict keys are `'lat'` and `'lon'` Sets the center point of the map. + mapbox_style : str (default `'basic'`, needs Mapbox API token) + Identifier of base map style, some of which require a Mapbox or Stadia + Maps API token to be set using + `plotly.express.set_mapbox_access_token()`. Allowed values which do not + require a token are `'open-street-map'`, `'white-bg'`, `'carto- + positron'`, `'carto-darkmatter'`. Allowed values which require a Mapbox + API token are `'basic'`, `'streets'`, `'outdoors'`, `'light'`, + `'dark'`, `'satellite'`, `'satellite-streets'`. Allowed values which + require a Stadia Maps API token are `'stamen-terrain'`, `'stamen- + toner'`, `'stamen-watercolor'`. + title : str + The figure title. + subtitle : str + The figure subtitle. + template : str or dict or plotly.graph_objects.layout.Template instance + The figure template name (must be a key in plotly.io.templates) or + definition. + width : int (default `None`) + The figure width in pixels. + height : int (default `None`) + The figure height in pixels. + + Returns + ------- + plotly.graph_objects.Figure """ warn( "*line_mapbox* is deprecated!" @@ -1570,9 +6156,6 @@ def line_mapbox( return make_figure(args=locals(), constructor=go.Scattermapbox) -line_mapbox.__doc__ = make_docstring(line_mapbox) - - def scatter_matrix( data_frame=None, dimensions=None, @@ -1604,15 +6187,128 @@ def scatter_matrix( represented by a multiple symbol marks, one in each cell of a grid of 2D scatter plots, which plot each pair of `dimensions` against each other. + + Parameters + ---------- + data_frame : DataFrame or array-like or dict + This argument needs to be passed for column names (and not keyword + names) to be used. Array-like and dict are transformed internally to a + pandas DataFrame. Optional: if missing, a DataFrame gets constructed + under the hood using the other arguments. + dimensions : list of str or int, or Series or array-like + Either names of columns in `data_frame`, or pandas Series, or + array_like objects Values from these columns are used for + multidimensional visualization. + color : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign color to marks. + symbol : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign symbols to marks. + size : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign mark sizes. + hover_name : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like appear in bold + in the hover tooltip. + hover_data : str, or list of str or int, or Series or array-like, or dict + Either a name or list of names of columns in `data_frame`, or pandas + Series, or array_like objects or a dict with column names as keys, with + values True (for default formatting) False (in order to remove this + column from hover information), or a formatting string, for example + ':.3f' or '|%a' or list-like data to appear in the hover tooltip or + tuples with a bool or formatting string as first element, and list-like + data to appear in hover as second element Values from these columns + appear as extra data in the hover tooltip. + custom_data : str, or list of str or int, or Series or array-like + Either name or list of names of columns in `data_frame`, or pandas + Series, or array_like objects Values from these columns are extra data, + to be used in widgets or Dash callbacks for example. This data is not + user-visible but is included in events emitted by the figure (lasso + selection etc.) + category_orders : dict with str keys and list of str values (default `{}`) + By default, in Python 3.6+, the order of categorical values in axes, + legends and facets depends on the order in which these values are first + encountered in `data_frame` (and no order is guaranteed by default in + Python below 3.6). This parameter is used to force a specific ordering + of values per column. The keys of this dict should correspond to column + names, and the values should be lists of strings corresponding to the + specific display order desired. + labels : dict with str keys and str values (default `{}`) + By default, column names are used in the figure for axis titles, legend + entries and hovers. This parameter allows this to be overridden. The + keys of this dict should correspond to column names, and the values + should correspond to the desired label to be displayed. + color_discrete_sequence : list of str + Strings should define valid CSS-colors. When `color` is set and the + values in the corresponding column are not numeric, values in that + column are assigned colors by cycling through `color_discrete_sequence` + in the order described in `category_orders`, unless the value of + `color` is a key in `color_discrete_map`. Various useful color + sequences are available in the `plotly.express.colors` submodules, + specifically `plotly.express.colors.qualitative`. + color_discrete_map : dict with str keys and str values (default `{}`) + String values should define valid CSS-colors Used to override + `color_discrete_sequence` to assign a specific colors to marks + corresponding with specific values. Keys in `color_discrete_map` should + be values in the column denoted by `color`. Alternatively, if the + values of `color` are valid colors, the string `'identity'` may be + passed to cause them to be used directly. + color_continuous_scale : list of str + Strings should define valid CSS-colors This list is used to build a + continuous color scale when the column denoted by `color` contains + numeric data. Various useful color scales are available in the + `plotly.express.colors` submodules, specifically + `plotly.express.colors.sequential`, `plotly.express.colors.diverging` + and `plotly.express.colors.cyclical`. + range_color : list of two numbers + If provided, overrides auto-scaling on the continuous color scale. + color_continuous_midpoint : number (default `None`) + If set, computes the bounds of the continuous color scale to have the + desired midpoint. Setting this value is recommended when using + `plotly.express.colors.diverging` color scales as the inputs to + `color_continuous_scale`. + symbol_sequence : list of str + Strings should define valid plotly.js symbols. When `symbol` is set, + values in that column are assigned symbols by cycling through + `symbol_sequence` in the order described in `category_orders`, unless + the value of `symbol` is a key in `symbol_map`. + symbol_map : dict with str keys and str values (default `{}`) + String values should define plotly.js symbols Used to override + `symbol_sequence` to assign a specific symbols to marks corresponding + with specific values. Keys in `symbol_map` should be values in the + column denoted by `symbol`. Alternatively, if the values of `symbol` + are valid symbol names, the string `'identity'` may be passed to cause + them to be used directly. + opacity : float + Value between 0 and 1. Sets the opacity for markers. + size_max : int (default `20`) + Set the maximum mark size when using `size`. + title : str + The figure title. + subtitle : str + The figure subtitle. + template : str or dict or plotly.graph_objects.layout.Template instance + The figure template name (must be a key in plotly.io.templates) or + definition. + width : int (default `None`) + The figure width in pixels. + height : int (default `None`) + The figure height in pixels. + + Returns + ------- + plotly.graph_objects.Figure """ return make_figure( args=locals(), constructor=go.Splom, layout_patch=dict(dragmode="select") ) -scatter_matrix.__doc__ = make_docstring(scatter_matrix) - - def parallel_coordinates( data_frame=None, dimensions=None, @@ -1631,13 +6327,60 @@ def parallel_coordinates( In a parallel coordinates plot, each row of `data_frame` is represented by a polyline mark which traverses a set of parallel axes, one for each of the `dimensions`. + + Parameters + ---------- + data_frame : DataFrame or array-like or dict + This argument needs to be passed for column names (and not keyword + names) to be used. Array-like and dict are transformed internally to a + pandas DataFrame. Optional: if missing, a DataFrame gets constructed + under the hood using the other arguments. + dimensions : list of str or int, or Series or array-like + Either names of columns in `data_frame`, or pandas Series, or + array_like objects Values from these columns are used for + multidimensional visualization. + color : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign color to marks. + labels : dict with str keys and str values (default `{}`) + By default, column names are used in the figure for axis titles, legend + entries and hovers. This parameter allows this to be overridden. The + keys of this dict should correspond to column names, and the values + should correspond to the desired label to be displayed. + color_continuous_scale : list of str + Strings should define valid CSS-colors This list is used to build a + continuous color scale when the column denoted by `color` contains + numeric data. Various useful color scales are available in the + `plotly.express.colors` submodules, specifically + `plotly.express.colors.sequential`, `plotly.express.colors.diverging` + and `plotly.express.colors.cyclical`. + range_color : list of two numbers + If provided, overrides auto-scaling on the continuous color scale. + color_continuous_midpoint : number (default `None`) + If set, computes the bounds of the continuous color scale to have the + desired midpoint. Setting this value is recommended when using + `plotly.express.colors.diverging` color scales as the inputs to + `color_continuous_scale`. + title : str + The figure title. + subtitle : str + The figure subtitle. + template : str or dict or plotly.graph_objects.layout.Template instance + The figure template name (must be a key in plotly.io.templates) or + definition. + width : int (default `None`) + The figure width in pixels. + height : int (default `None`) + The figure height in pixels. + + Returns + ------- + plotly.graph_objects.Figure """ return make_figure(args=locals(), constructor=go.Parcoords) -parallel_coordinates.__doc__ = make_docstring(parallel_coordinates) - - def parallel_categories( data_frame=None, dimensions=None, @@ -1658,13 +6401,64 @@ def parallel_categories( `data_frame` is grouped with other rows that share the same values of `dimensions` and then plotted as a polyline mark through a set of parallel axes, one for each of the `dimensions`. + + Parameters + ---------- + data_frame : DataFrame or array-like or dict + This argument needs to be passed for column names (and not keyword + names) to be used. Array-like and dict are transformed internally to a + pandas DataFrame. Optional: if missing, a DataFrame gets constructed + under the hood using the other arguments. + dimensions : list of str or int, or Series or array-like + Either names of columns in `data_frame`, or pandas Series, or + array_like objects Values from these columns are used for + multidimensional visualization. + color : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign color to marks. + labels : dict with str keys and str values (default `{}`) + By default, column names are used in the figure for axis titles, legend + entries and hovers. This parameter allows this to be overridden. The + keys of this dict should correspond to column names, and the values + should correspond to the desired label to be displayed. + color_continuous_scale : list of str + Strings should define valid CSS-colors This list is used to build a + continuous color scale when the column denoted by `color` contains + numeric data. Various useful color scales are available in the + `plotly.express.colors` submodules, specifically + `plotly.express.colors.sequential`, `plotly.express.colors.diverging` + and `plotly.express.colors.cyclical`. + range_color : list of two numbers + If provided, overrides auto-scaling on the continuous color scale. + color_continuous_midpoint : number (default `None`) + If set, computes the bounds of the continuous color scale to have the + desired midpoint. Setting this value is recommended when using + `plotly.express.colors.diverging` color scales as the inputs to + `color_continuous_scale`. + title : str + The figure title. + subtitle : str + The figure subtitle. + template : str or dict or plotly.graph_objects.layout.Template instance + The figure template name (must be a key in plotly.io.templates) or + definition. + width : int (default `None`) + The figure width in pixels. + height : int (default `None`) + The figure height in pixels. + dimensions_max_cardinality : int (default 50) + When `dimensions` is `None` and `data_frame` is provided, columns with + more than this number of unique values are excluded from the output. + Not used when `dimensions` is passed. + + Returns + ------- + plotly.graph_objects.Figure """ return make_figure(args=locals(), constructor=go.Parcats) -parallel_categories.__doc__ = make_docstring(parallel_categories) - - def pie( data_frame=None, names=None, @@ -1693,6 +6487,110 @@ def pie( """ In a pie plot, each row of `data_frame` is represented as a sector of a pie. + + Parameters + ---------- + data_frame : DataFrame or array-like or dict + This argument needs to be passed for column names (and not keyword + names) to be used. Array-like and dict are transformed internally to a + pandas DataFrame. Optional: if missing, a DataFrame gets constructed + under the hood using the other arguments. + names : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used as + labels for sectors. + values : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + set values associated to sectors. + color : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign color to marks. + facet_row : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign marks to facetted subplots in the vertical direction. + facet_col : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign marks to facetted subplots in the horizontal direction. + facet_col_wrap : int + Maximum number of facet columns. Wraps the column variable at this + width, so that the column facets span multiple rows. Ignored if 0, and + forced to 0 if `facet_row` or a `marginal` is set. + facet_row_spacing : float between 0 and 1 + Spacing between facet rows, in paper units. Default is 0.03 or 0.07 + when facet_col_wrap is used. + facet_col_spacing : float between 0 and 1 + Spacing between facet columns, in paper units Default is 0.02. + color_discrete_sequence : list of str + Strings should define valid CSS-colors. When `color` is set and the + values in the corresponding column are not numeric, values in that + column are assigned colors by cycling through `color_discrete_sequence` + in the order described in `category_orders`, unless the value of + `color` is a key in `color_discrete_map`. Various useful color + sequences are available in the `plotly.express.colors` submodules, + specifically `plotly.express.colors.qualitative`. + color_discrete_map : dict with str keys and str values (default `{}`) + String values should define valid CSS-colors Used to override + `color_discrete_sequence` to assign a specific colors to marks + corresponding with specific values. Keys in `color_discrete_map` should + be values in the column denoted by `color`. Alternatively, if the + values of `color` are valid colors, the string `'identity'` may be + passed to cause them to be used directly. + hover_name : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like appear in bold + in the hover tooltip. + hover_data : str, or list of str or int, or Series or array-like, or dict + Either a name or list of names of columns in `data_frame`, or pandas + Series, or array_like objects or a dict with column names as keys, with + values True (for default formatting) False (in order to remove this + column from hover information), or a formatting string, for example + ':.3f' or '|%a' or list-like data to appear in the hover tooltip or + tuples with a bool or formatting string as first element, and list-like + data to appear in hover as second element Values from these columns + appear as extra data in the hover tooltip. + custom_data : str, or list of str or int, or Series or array-like + Either name or list of names of columns in `data_frame`, or pandas + Series, or array_like objects Values from these columns are extra data, + to be used in widgets or Dash callbacks for example. This data is not + user-visible but is included in events emitted by the figure (lasso + selection etc.) + category_orders : dict with str keys and list of str values (default `{}`) + By default, in Python 3.6+, the order of categorical values in axes, + legends and facets depends on the order in which these values are first + encountered in `data_frame` (and no order is guaranteed by default in + Python below 3.6). This parameter is used to force a specific ordering + of values per column. The keys of this dict should correspond to column + names, and the values should be lists of strings corresponding to the + specific display order desired. + labels : dict with str keys and str values (default `{}`) + By default, column names are used in the figure for axis titles, legend + entries and hovers. This parameter allows this to be overridden. The + keys of this dict should correspond to column names, and the values + should correspond to the desired label to be displayed. + title : str + The figure title. + subtitle : str + The figure subtitle. + template : str or dict or plotly.graph_objects.layout.Template instance + The figure template name (must be a key in plotly.io.templates) or + definition. + width : int (default `None`) + The figure width in pixels. + height : int (default `None`) + The figure height in pixels. + opacity : float + Value between 0 and 1. Sets the opacity for markers. + hole : float + Sets the fraction of the radius to cut out of the pie.Use this to make + a donut chart. + + Returns + ------- + plotly.graph_objects.Figure """ if color_discrete_sequence is not None: layout_patch = {"piecolorway": color_discrete_sequence} @@ -1706,18 +6604,6 @@ def pie( ) -pie.__doc__ = make_docstring( - pie, - override_dict=dict( - hole=[ - "float", - "Sets the fraction of the radius to cut out of the pie." - "Use this to make a donut chart.", - ], - ), -) - - def sunburst( data_frame=None, names=None, @@ -1746,6 +6632,116 @@ def sunburst( """ A sunburst plot represents hierarchial data as sectors laid out over several levels of concentric rings. + + Parameters + ---------- + data_frame : DataFrame or array-like or dict + This argument needs to be passed for column names (and not keyword + names) to be used. Array-like and dict are transformed internally to a + pandas DataFrame. Optional: if missing, a DataFrame gets constructed + under the hood using the other arguments. + names : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used as + labels for sectors. + values : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + set values associated to sectors. + parents : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used as + parents in sunburst and treemap charts. + path : list of str or int, or Series or array-like + Either names of columns in `data_frame`, or pandas Series, or + array_like objects List of columns names or columns of a rectangular + dataframe defining the hierarchy of sectors, from root to leaves. An + error is raised if path AND ids or parents is passed + ids : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + set ids of sectors + color : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign color to marks. + color_continuous_scale : list of str + Strings should define valid CSS-colors This list is used to build a + continuous color scale when the column denoted by `color` contains + numeric data. Various useful color scales are available in the + `plotly.express.colors` submodules, specifically + `plotly.express.colors.sequential`, `plotly.express.colors.diverging` + and `plotly.express.colors.cyclical`. + range_color : list of two numbers + If provided, overrides auto-scaling on the continuous color scale. + color_continuous_midpoint : number (default `None`) + If set, computes the bounds of the continuous color scale to have the + desired midpoint. Setting this value is recommended when using + `plotly.express.colors.diverging` color scales as the inputs to + `color_continuous_scale`. + color_discrete_sequence : list of str + Strings should define valid CSS-colors. When `color` is set and the + values in the corresponding column are not numeric, values in that + column are assigned colors by cycling through `color_discrete_sequence` + in the order described in `category_orders`, unless the value of + `color` is a key in `color_discrete_map`. Various useful color + sequences are available in the `plotly.express.colors` submodules, + specifically `plotly.express.colors.qualitative`. + color_discrete_map : dict with str keys and str values (default `{}`) + String values should define valid CSS-colors Used to override + `color_discrete_sequence` to assign a specific colors to marks + corresponding with specific values. Keys in `color_discrete_map` should + be values in the column denoted by `color`. Alternatively, if the + values of `color` are valid colors, the string `'identity'` may be + passed to cause them to be used directly. + hover_name : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like appear in bold + in the hover tooltip. + hover_data : str, or list of str or int, or Series or array-like, or dict + Either a name or list of names of columns in `data_frame`, or pandas + Series, or array_like objects or a dict with column names as keys, with + values True (for default formatting) False (in order to remove this + column from hover information), or a formatting string, for example + ':.3f' or '|%a' or list-like data to appear in the hover tooltip or + tuples with a bool or formatting string as first element, and list-like + data to appear in hover as second element Values from these columns + appear as extra data in the hover tooltip. + custom_data : str, or list of str or int, or Series or array-like + Either name or list of names of columns in `data_frame`, or pandas + Series, or array_like objects Values from these columns are extra data, + to be used in widgets or Dash callbacks for example. This data is not + user-visible but is included in events emitted by the figure (lasso + selection etc.) + labels : dict with str keys and str values (default `{}`) + By default, column names are used in the figure for axis titles, legend + entries and hovers. This parameter allows this to be overridden. The + keys of this dict should correspond to column names, and the values + should correspond to the desired label to be displayed. + title : str + The figure title. + subtitle : str + The figure subtitle. + template : str or dict or plotly.graph_objects.layout.Template instance + The figure template name (must be a key in plotly.io.templates) or + definition. + width : int (default `None`) + The figure width in pixels. + height : int (default `None`) + The figure height in pixels. + branchvalues : str + 'total' or 'remainder' Determines how the items in `values` are summed. + Whenset to 'total', items in `values` are taken to be valueof all its + descendants. When set to 'remainder', itemsin `values` corresponding to + the root and the branches:sectors are taken to be the extra part not + part of thesum of the values at their leaves. + maxdepth : int + Positive integer Sets the number of rendered sectors from any given + `level`. Set `maxdepth` to -1 to render all thelevels in the hierarchy. + + Returns + ------- + plotly.graph_objects.Figure """ if color_discrete_sequence is not None: layout_patch = {"sunburstcolorway": color_discrete_sequence} @@ -1766,9 +6762,6 @@ def sunburst( ) -sunburst.__doc__ = make_docstring(sunburst) - - def treemap( data_frame=None, names=None, @@ -1797,6 +6790,116 @@ def treemap( """ A treemap plot represents hierarchial data as nested rectangular sectors. + + Parameters + ---------- + data_frame : DataFrame or array-like or dict + This argument needs to be passed for column names (and not keyword + names) to be used. Array-like and dict are transformed internally to a + pandas DataFrame. Optional: if missing, a DataFrame gets constructed + under the hood using the other arguments. + names : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used as + labels for sectors. + values : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + set values associated to sectors. + parents : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used as + parents in sunburst and treemap charts. + ids : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + set ids of sectors + path : list of str or int, or Series or array-like + Either names of columns in `data_frame`, or pandas Series, or + array_like objects List of columns names or columns of a rectangular + dataframe defining the hierarchy of sectors, from root to leaves. An + error is raised if path AND ids or parents is passed + color : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign color to marks. + color_continuous_scale : list of str + Strings should define valid CSS-colors This list is used to build a + continuous color scale when the column denoted by `color` contains + numeric data. Various useful color scales are available in the + `plotly.express.colors` submodules, specifically + `plotly.express.colors.sequential`, `plotly.express.colors.diverging` + and `plotly.express.colors.cyclical`. + range_color : list of two numbers + If provided, overrides auto-scaling on the continuous color scale. + color_continuous_midpoint : number (default `None`) + If set, computes the bounds of the continuous color scale to have the + desired midpoint. Setting this value is recommended when using + `plotly.express.colors.diverging` color scales as the inputs to + `color_continuous_scale`. + color_discrete_sequence : list of str + Strings should define valid CSS-colors. When `color` is set and the + values in the corresponding column are not numeric, values in that + column are assigned colors by cycling through `color_discrete_sequence` + in the order described in `category_orders`, unless the value of + `color` is a key in `color_discrete_map`. Various useful color + sequences are available in the `plotly.express.colors` submodules, + specifically `plotly.express.colors.qualitative`. + color_discrete_map : dict with str keys and str values (default `{}`) + String values should define valid CSS-colors Used to override + `color_discrete_sequence` to assign a specific colors to marks + corresponding with specific values. Keys in `color_discrete_map` should + be values in the column denoted by `color`. Alternatively, if the + values of `color` are valid colors, the string `'identity'` may be + passed to cause them to be used directly. + hover_name : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like appear in bold + in the hover tooltip. + hover_data : str, or list of str or int, or Series or array-like, or dict + Either a name or list of names of columns in `data_frame`, or pandas + Series, or array_like objects or a dict with column names as keys, with + values True (for default formatting) False (in order to remove this + column from hover information), or a formatting string, for example + ':.3f' or '|%a' or list-like data to appear in the hover tooltip or + tuples with a bool or formatting string as first element, and list-like + data to appear in hover as second element Values from these columns + appear as extra data in the hover tooltip. + custom_data : str, or list of str or int, or Series or array-like + Either name or list of names of columns in `data_frame`, or pandas + Series, or array_like objects Values from these columns are extra data, + to be used in widgets or Dash callbacks for example. This data is not + user-visible but is included in events emitted by the figure (lasso + selection etc.) + labels : dict with str keys and str values (default `{}`) + By default, column names are used in the figure for axis titles, legend + entries and hovers. This parameter allows this to be overridden. The + keys of this dict should correspond to column names, and the values + should correspond to the desired label to be displayed. + title : str + The figure title. + subtitle : str + The figure subtitle. + template : str or dict or plotly.graph_objects.layout.Template instance + The figure template name (must be a key in plotly.io.templates) or + definition. + width : int (default `None`) + The figure width in pixels. + height : int (default `None`) + The figure height in pixels. + branchvalues : str + 'total' or 'remainder' Determines how the items in `values` are summed. + Whenset to 'total', items in `values` are taken to be valueof all its + descendants. When set to 'remainder', itemsin `values` corresponding to + the root and the branches:sectors are taken to be the extra part not + part of thesum of the values at their leaves. + maxdepth : int + Positive integer Sets the number of rendered sectors from any given + `level`. Set `maxdepth` to -1 to render all thelevels in the hierarchy. + + Returns + ------- + plotly.graph_objects.Figure """ if color_discrete_sequence is not None: layout_patch = {"treemapcolorway": color_discrete_sequence} @@ -1817,9 +6920,6 @@ def treemap( ) -treemap.__doc__ = make_docstring(treemap) - - def icicle( data_frame=None, names=None, @@ -1848,6 +6948,116 @@ def icicle( """ An icicle plot represents hierarchial data with adjoined rectangular sectors that all cascade from root down to leaf in one direction. + + Parameters + ---------- + data_frame : DataFrame or array-like or dict + This argument needs to be passed for column names (and not keyword + names) to be used. Array-like and dict are transformed internally to a + pandas DataFrame. Optional: if missing, a DataFrame gets constructed + under the hood using the other arguments. + names : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used as + labels for sectors. + values : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + set values associated to sectors. + parents : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used as + parents in sunburst and treemap charts. + path : list of str or int, or Series or array-like + Either names of columns in `data_frame`, or pandas Series, or + array_like objects List of columns names or columns of a rectangular + dataframe defining the hierarchy of sectors, from root to leaves. An + error is raised if path AND ids or parents is passed + ids : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + set ids of sectors + color : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign color to marks. + color_continuous_scale : list of str + Strings should define valid CSS-colors This list is used to build a + continuous color scale when the column denoted by `color` contains + numeric data. Various useful color scales are available in the + `plotly.express.colors` submodules, specifically + `plotly.express.colors.sequential`, `plotly.express.colors.diverging` + and `plotly.express.colors.cyclical`. + range_color : list of two numbers + If provided, overrides auto-scaling on the continuous color scale. + color_continuous_midpoint : number (default `None`) + If set, computes the bounds of the continuous color scale to have the + desired midpoint. Setting this value is recommended when using + `plotly.express.colors.diverging` color scales as the inputs to + `color_continuous_scale`. + color_discrete_sequence : list of str + Strings should define valid CSS-colors. When `color` is set and the + values in the corresponding column are not numeric, values in that + column are assigned colors by cycling through `color_discrete_sequence` + in the order described in `category_orders`, unless the value of + `color` is a key in `color_discrete_map`. Various useful color + sequences are available in the `plotly.express.colors` submodules, + specifically `plotly.express.colors.qualitative`. + color_discrete_map : dict with str keys and str values (default `{}`) + String values should define valid CSS-colors Used to override + `color_discrete_sequence` to assign a specific colors to marks + corresponding with specific values. Keys in `color_discrete_map` should + be values in the column denoted by `color`. Alternatively, if the + values of `color` are valid colors, the string `'identity'` may be + passed to cause them to be used directly. + hover_name : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like appear in bold + in the hover tooltip. + hover_data : str, or list of str or int, or Series or array-like, or dict + Either a name or list of names of columns in `data_frame`, or pandas + Series, or array_like objects or a dict with column names as keys, with + values True (for default formatting) False (in order to remove this + column from hover information), or a formatting string, for example + ':.3f' or '|%a' or list-like data to appear in the hover tooltip or + tuples with a bool or formatting string as first element, and list-like + data to appear in hover as second element Values from these columns + appear as extra data in the hover tooltip. + custom_data : str, or list of str or int, or Series or array-like + Either name or list of names of columns in `data_frame`, or pandas + Series, or array_like objects Values from these columns are extra data, + to be used in widgets or Dash callbacks for example. This data is not + user-visible but is included in events emitted by the figure (lasso + selection etc.) + labels : dict with str keys and str values (default `{}`) + By default, column names are used in the figure for axis titles, legend + entries and hovers. This parameter allows this to be overridden. The + keys of this dict should correspond to column names, and the values + should correspond to the desired label to be displayed. + title : str + The figure title. + subtitle : str + The figure subtitle. + template : str or dict or plotly.graph_objects.layout.Template instance + The figure template name (must be a key in plotly.io.templates) or + definition. + width : int (default `None`) + The figure width in pixels. + height : int (default `None`) + The figure height in pixels. + branchvalues : str + 'total' or 'remainder' Determines how the items in `values` are summed. + Whenset to 'total', items in `values` are taken to be valueof all its + descendants. When set to 'remainder', itemsin `values` corresponding to + the root and the branches:sectors are taken to be the extra part not + part of thesum of the values at their leaves. + maxdepth : int + Positive integer Sets the number of rendered sectors from any given + `level`. Set `maxdepth` to -1 to render all thelevels in the hierarchy. + + Returns + ------- + plotly.graph_objects.Figure """ if color_discrete_sequence is not None: layout_patch = {"iciclecolorway": color_discrete_sequence} @@ -1868,9 +7078,6 @@ def icicle( ) -icicle.__doc__ = make_docstring(icicle) - - def funnel( data_frame=None, x=None, @@ -1906,13 +7113,146 @@ def funnel( """ In a funnel plot, each row of `data_frame` is represented as a rectangular sector of a funnel. + + Parameters + ---------- + data_frame : DataFrame or array-like or dict + This argument needs to be passed for column names (and not keyword + names) to be used. Array-like and dict are transformed internally to a + pandas DataFrame. Optional: if missing, a DataFrame gets constructed + under the hood using the other arguments. + x : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + position marks along the x axis in cartesian coordinates. Either `x` or + `y` can optionally be a list of column references or array_likes, in + which case the data will be treated as if it were 'wide' rather than + 'long'. + y : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + position marks along the y axis in cartesian coordinates. Either `x` or + `y` can optionally be a list of column references or array_likes, in + which case the data will be treated as if it were 'wide' rather than + 'long'. + color : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign color to marks. + facet_row : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign marks to facetted subplots in the vertical direction. + facet_col : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign marks to facetted subplots in the horizontal direction. + facet_col_wrap : int + Maximum number of facet columns. Wraps the column variable at this + width, so that the column facets span multiple rows. Ignored if 0, and + forced to 0 if `facet_row` or a `marginal` is set. + facet_row_spacing : float between 0 and 1 + Spacing between facet rows, in paper units. Default is 0.03 or 0.07 + when facet_col_wrap is used. + facet_col_spacing : float between 0 and 1 + Spacing between facet columns, in paper units Default is 0.02. + hover_name : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like appear in bold + in the hover tooltip. + hover_data : str, or list of str or int, or Series or array-like, or dict + Either a name or list of names of columns in `data_frame`, or pandas + Series, or array_like objects or a dict with column names as keys, with + values True (for default formatting) False (in order to remove this + column from hover information), or a formatting string, for example + ':.3f' or '|%a' or list-like data to appear in the hover tooltip or + tuples with a bool or formatting string as first element, and list-like + data to appear in hover as second element Values from these columns + appear as extra data in the hover tooltip. + custom_data : str, or list of str or int, or Series or array-like + Either name or list of names of columns in `data_frame`, or pandas + Series, or array_like objects Values from these columns are extra data, + to be used in widgets or Dash callbacks for example. This data is not + user-visible but is included in events emitted by the figure (lasso + selection etc.) + text : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like appear in the + figure as text labels. + animation_frame : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign marks to animation frames. + animation_group : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + provide object-constancy across animation frames: rows with matching + `animation_group`s will be treated as if they describe the same object + in each frame. + category_orders : dict with str keys and list of str values (default `{}`) + By default, in Python 3.6+, the order of categorical values in axes, + legends and facets depends on the order in which these values are first + encountered in `data_frame` (and no order is guaranteed by default in + Python below 3.6). This parameter is used to force a specific ordering + of values per column. The keys of this dict should correspond to column + names, and the values should be lists of strings corresponding to the + specific display order desired. + labels : dict with str keys and str values (default `{}`) + By default, column names are used in the figure for axis titles, legend + entries and hovers. This parameter allows this to be overridden. The + keys of this dict should correspond to column names, and the values + should correspond to the desired label to be displayed. + color_discrete_sequence : list of str + Strings should define valid CSS-colors. When `color` is set and the + values in the corresponding column are not numeric, values in that + column are assigned colors by cycling through `color_discrete_sequence` + in the order described in `category_orders`, unless the value of + `color` is a key in `color_discrete_map`. Various useful color + sequences are available in the `plotly.express.colors` submodules, + specifically `plotly.express.colors.qualitative`. + color_discrete_map : dict with str keys and str values (default `{}`) + String values should define valid CSS-colors Used to override + `color_discrete_sequence` to assign a specific colors to marks + corresponding with specific values. Keys in `color_discrete_map` should + be values in the column denoted by `color`. Alternatively, if the + values of `color` are valid colors, the string `'identity'` may be + passed to cause them to be used directly. + opacity : float + Value between 0 and 1. Sets the opacity for markers. + orientation : str, one of `'h'` for horizontal or `'v'` for vertical. + (default `'v'` if `x` and `y` are provided and both continuous or both + categorical, otherwise `'v'`(`'h'`) if `x`(`y`) is categorical and + `y`(`x`) is continuous, otherwise `'v'`(`'h'`) if only `x`(`y`) is + provided) + log_x : boolean (default `False`) + If `True`, the x-axis is log-scaled in cartesian coordinates. + log_y : boolean (default `False`) + If `True`, the y-axis is log-scaled in cartesian coordinates. + range_x : list of two numbers + If provided, overrides auto-scaling on the x-axis in cartesian + coordinates. + range_y : list of two numbers + If provided, overrides auto-scaling on the y-axis in cartesian + coordinates. + title : str + The figure title. + subtitle : str + The figure subtitle. + template : str or dict or plotly.graph_objects.layout.Template instance + The figure template name (must be a key in plotly.io.templates) or + definition. + width : int (default `None`) + The figure width in pixels. + height : int (default `None`) + The figure height in pixels. + + Returns + ------- + plotly.graph_objects.Figure """ return make_figure(args=locals(), constructor=go.Funnel) -funnel.__doc__ = make_docstring(funnel, append_dict=_cartesian_append_dict) - - def funnel_area( data_frame=None, names=None, @@ -1934,6 +7274,82 @@ def funnel_area( """ In a funnel area plot, each row of `data_frame` is represented as a trapezoidal sector of a funnel. + + Parameters + ---------- + data_frame : DataFrame or array-like or dict + This argument needs to be passed for column names (and not keyword + names) to be used. Array-like and dict are transformed internally to a + pandas DataFrame. Optional: if missing, a DataFrame gets constructed + under the hood using the other arguments. + names : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used as + labels for sectors. + values : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + set values associated to sectors. + color : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign color to marks. + color_discrete_sequence : list of str + Strings should define valid CSS-colors. When `color` is set and the + values in the corresponding column are not numeric, values in that + column are assigned colors by cycling through `color_discrete_sequence` + in the order described in `category_orders`, unless the value of + `color` is a key in `color_discrete_map`. Various useful color + sequences are available in the `plotly.express.colors` submodules, + specifically `plotly.express.colors.qualitative`. + color_discrete_map : dict with str keys and str values (default `{}`) + String values should define valid CSS-colors Used to override + `color_discrete_sequence` to assign a specific colors to marks + corresponding with specific values. Keys in `color_discrete_map` should + be values in the column denoted by `color`. Alternatively, if the + values of `color` are valid colors, the string `'identity'` may be + passed to cause them to be used directly. + hover_name : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like appear in bold + in the hover tooltip. + hover_data : str, or list of str or int, or Series or array-like, or dict + Either a name or list of names of columns in `data_frame`, or pandas + Series, or array_like objects or a dict with column names as keys, with + values True (for default formatting) False (in order to remove this + column from hover information), or a formatting string, for example + ':.3f' or '|%a' or list-like data to appear in the hover tooltip or + tuples with a bool or formatting string as first element, and list-like + data to appear in hover as second element Values from these columns + appear as extra data in the hover tooltip. + custom_data : str, or list of str or int, or Series or array-like + Either name or list of names of columns in `data_frame`, or pandas + Series, or array_like objects Values from these columns are extra data, + to be used in widgets or Dash callbacks for example. This data is not + user-visible but is included in events emitted by the figure (lasso + selection etc.) + labels : dict with str keys and str values (default `{}`) + By default, column names are used in the figure for axis titles, legend + entries and hovers. This parameter allows this to be overridden. The + keys of this dict should correspond to column names, and the values + should correspond to the desired label to be displayed. + title : str + The figure title. + subtitle : str + The figure subtitle. + template : str or dict or plotly.graph_objects.layout.Template instance + The figure template name (must be a key in plotly.io.templates) or + definition. + width : int (default `None`) + The figure width in pixels. + height : int (default `None`) + The figure height in pixels. + opacity : float + Value between 0 and 1. Sets the opacity for markers. + + Returns + ------- + plotly.graph_objects.Figure """ if color_discrete_sequence is not None: layout_patch = {"funnelareacolorway": color_discrete_sequence} @@ -1945,6 +7361,3 @@ def funnel_area( trace_patch=dict(showlegend=(names is not None)), layout_patch=layout_patch, ) - - -funnel_area.__doc__ = make_docstring(funnel_area) diff --git a/plotly/express/_doc.py b/plotly/express/_doc.py index 59faac4c0b..7bb2be5677 100644 --- a/plotly/express/_doc.py +++ b/plotly/express/_doc.py @@ -607,34 +607,3 @@ "A string like `'.2f'` will be interpreted as a `texttemplate` numeric formatting directive.", ], ) - - -def make_docstring(fn, override_dict=None, append_dict=None): - override_dict = {} if override_dict is None else override_dict - append_dict = {} if append_dict is None else append_dict - tw = TextWrapper( - width=75, - initial_indent=" ", - subsequent_indent=" ", - break_on_hyphens=False, - ) - result = (fn.__doc__ or "") + "\nParameters\n----------\n" - for param in getfullargspec(fn)[0]: - if override_dict.get(param): - param_doc = list(override_dict[param]) - else: - param_doc = list(docs[param]) - if append_dict.get(param): - param_doc += append_dict[param] - param_desc_list = param_doc[1:] - param_desc = ( - tw.fill(" ".join(param_desc_list or "")) - if param in docs or param in override_dict - else "(documentation missing from map)" - ) - - param_type = param_doc[0] - result += "%s: %s\n%s\n" % (param, param_type, param_desc) - result += "\nReturns\n-------\n" - result += " plotly.graph_objects.Figure" - return result diff --git a/plotly/express/_imshow.py b/plotly/express/_imshow.py index ce6ddb8428..83dee3e3dc 100644 --- a/plotly/express/_imshow.py +++ b/plotly/express/_imshow.py @@ -87,7 +87,7 @@ def imshow( Parameters ---------- - img: array-like image, or xarray + img : array-like image, or xarray The image data. Supported array shapes are - (M, N): an image with scalar data. The data is visualized @@ -115,28 +115,28 @@ def imshow( names are used for axis titles, and long name for the colorbar title (unless overridden in ``labels``). Possible keys are: x, y, and color. - x, y: list-like, optional + x, y : list-like, optional x and y are used to label the axes of single-channel heatmap visualizations and their lengths must match the lengths of the second and first dimensions of the img argument. They are auto-populated if the input is an xarray. - animation_frame: int or str, optional (default None) + animation_frame : int or str, optional (default None) axis number along which the image array is sliced to create an animation plot. If `img` is an xarray, `animation_frame` can be the name of one the dimensions. - facet_col: int or str, optional (default None) + facet_col : int or str, optional (default None) axis number along which the image array is sliced to create a facetted plot. If `img` is an xarray, `facet_col` can be the name of one the dimensions. - facet_col_wrap: int + facet_col_wrap : int Maximum number of facet columns. Wraps the column variable at this width, so that the column facets span multiple rows. Ignored if `facet_col` is None. - facet_col_spacing: float between 0 and 1 + facet_col_spacing : float between 0 and 1 Spacing between facet columns, in paper units. Default is 0.02. - facet_row_spacing: float between 0 and 1 + facet_row_spacing : float between 0 and 1 Spacing between facet rows created when ``facet_col_wrap`` is used, in paper units. Default is 0.0.7. @@ -164,10 +164,10 @@ def imshow( width : number The figure width in pixels. - height: number + height : number The figure height in pixels. - aspect: 'equal', 'auto', or None + aspect : 'equal', 'auto', or None - 'equal': Ensures an aspect ratio of 1 or pixels (square pixels) - 'auto': The axes is kept fixed and the aspect ratio of pixels is adjusted so that the data fit in the axes. In general, this will @@ -175,13 +175,13 @@ def imshow( - if None, 'equal' is used for numpy arrays and 'auto' for xarrays (which have typically heterogeneous coordinates) - contrast_rescaling: 'minmax', 'infer', or None + contrast_rescaling : 'minmax', 'infer', or None how to determine data values corresponding to the bounds of the color range, when zmin or zmax are not passed. If `minmax`, the min and max values of the image are used. If `infer`, a heuristic based on the image data type is used. - binary_string: bool, default None + binary_string : bool, default None if True, the image data are first rescaled and encoded as uint8 and then passed to plotly.js as a b64 PNG string. If False, data are passed unchanged as a numerical array. Setting to True may lead to performance @@ -191,12 +191,12 @@ def imshow( represented as grayscale and with no colorbar if use_binary_string is True. - binary_backend: str, 'auto' (default), 'pil' or 'pypng' + binary_backend : str, 'auto' (default), 'pil' or 'pypng' Third-party package for the transformation of numpy arrays to png b64 strings. If 'auto', Pillow is used if installed, otherwise pypng. - binary_compression_level: int, between 0 and 9 (default 4) + binary_compression_level : int, between 0 and 9 (default 4) png compression level to be passed to the backend when transforming an array to a png b64 string. Increasing `binary_compression` decreases the size of the png string, but the compression step takes more time. For most @@ -204,12 +204,12 @@ def imshow( test `len(fig.data[0].source)` and to time the execution of `imshow` to tune the level of compression. 0 means no compression (not recommended). - binary_format: str, 'png' (default) or 'jpg' + binary_format : str, 'png' (default) or 'jpg' compression format used to generate b64 string. 'png' is recommended since it uses lossless compression, but 'jpg' (lossy) compression can result if smaller binary strings for natural images. - text_auto: bool or str (default `False`) + text_auto : bool or str (default `False`) If `True` or a string, single-channel `img` values will be displayed as text. A string like `'.2f'` will be interpreted as a `texttemplate` numeric formatting directive. diff --git a/plotly/figure_factory/_hexbin_mapbox.py b/plotly/figure_factory/_hexbin_mapbox.py index c76352248b..efff98ef4f 100644 --- a/plotly/figure_factory/_hexbin_mapbox.py +++ b/plotly/figure_factory/_hexbin_mapbox.py @@ -1,5 +1,4 @@ from plotly.express._core import build_dataframe -from plotly.express._doc import make_docstring from plotly.express._chart_types import choropleth_mapbox, scatter_mapbox import narwhals.stable.v1 as nw import numpy as np @@ -350,6 +349,106 @@ def create_hexbin_mapbox( ): """ Returns a figure aggregating scattered points into connected hexagons + + Parameters + ---------- + data_frame : DataFrame or array-like or dict + This argument needs to be passed for column names (and not keyword + names) to be used. Array-like and dict are transformed internally to a + pandas DataFrame. Optional: if missing, a DataFrame gets constructed + under the hood using the other arguments. + lat : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + position marks according to latitude on a map. + lon : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + position marks according to longitude on a map. + color : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign color to marks. + nx_hexagon : int + Number of hexagons (horizontally) to be created + agg_func : function + Numpy array aggregator, it must take as input a 1D array and output a + scalar value. + animation_frame : str or int or Series or array-like + Either a name of a column in `data_frame`, or a pandas Series or + array_like object. Values from this column or array_like are used to + assign marks to animation frames. + color_discrete_sequence : list of str + Strings should define valid CSS-colors. When `color` is set and the + values in the corresponding column are not numeric, values in that + column are assigned colors by cycling through `color_discrete_sequence` + in the order described in `category_orders`, unless the value of + `color` is a key in `color_discrete_map`. Various useful color + sequences are available in the `plotly.express.colors` submodules, + specifically `plotly.express.colors.qualitative`. + color_discrete_map : dict with str keys and str values (default `{}`) + String values should define valid CSS-colors Used to override + `color_discrete_sequence` to assign a specific colors to marks + corresponding with specific values. Keys in `color_discrete_map` should + be values in the column denoted by `color`. Alternatively, if the + values of `color` are valid colors, the string `'identity'` may be + passed to cause them to be used directly. + labels : dict with str keys and str values (default `{}`) + By default, column names are used in the figure for axis titles, legend + entries and hovers. This parameter allows this to be overridden. The + keys of this dict should correspond to column names, and the values + should correspond to the desired label to be displayed. + color_continuous_scale : list of str + Strings should define valid CSS-colors This list is used to build a + continuous color scale when the column denoted by `color` contains + numeric data. Various useful color scales are available in the + `plotly.express.colors` submodules, specifically + `plotly.express.colors.sequential`, `plotly.express.colors.diverging` + and `plotly.express.colors.cyclical`. + range_color : list of two numbers + If provided, overrides auto-scaling on the continuous color scale. + color_continuous_midpoint : number (default `None`) + If set, computes the bounds of the continuous color scale to have the + desired midpoint. Setting this value is recommended when using + `plotly.express.colors.diverging` color scales as the inputs to + `color_continuous_scale`. + opacity : float + Value between 0 and 1. Sets the opacity for markers. + zoom : int (default `8`) + Between 0 and 20. Sets map zoom level. + center : dict + Dict keys are `'lat'` and `'lon'` Sets the center point of the map. + mapbox_style : str (default `'basic'`, needs Mapbox API token) + Identifier of base map style, some of which require a Mapbox or Stadia + Maps API token to be set using + `plotly.express.set_mapbox_access_token()`. Allowed values which do not + require a token are `'open-street-map'`, `'white-bg'`, `'carto- + positron'`, `'carto-darkmatter'`. Allowed values which require a Mapbox + API token are `'basic'`, `'streets'`, `'outdoors'`, `'light'`, + `'dark'`, `'satellite'`, `'satellite-streets'`. Allowed values which + require a Stadia Maps API token are `'stamen-terrain'`, `'stamen- + toner'`, `'stamen-watercolor'`. + title : str + The figure title. + template : str or dict or plotly.graph_objects.layout.Template instance + The figure template name (must be a key in plotly.io.templates) or + definition. + width : int (default `None`) + The figure width in pixels. + height : int (default `None`) + The figure height in pixels. + min_count : int + Minimum number of points in a hexagon for it to be displayed. If None + and color is not set, display all hexagons. If None and color is set, + only display hexagons that contain points. + show_original_data : bool + Whether to show the original data on top of the hexbin aggregation. + original_data_marker : dict + Scattermapbox marker options. + + Returns + ------- + plotly.graph_objects.Figure """ args = build_dataframe(args=locals(), constructor=None) native_namespace = nw.get_native_namespace(args["data_frame"]) @@ -500,27 +599,3 @@ def create_hexbin_mapbox( ] return fig - - -create_hexbin_mapbox.__doc__ = make_docstring( - create_hexbin_mapbox, - override_dict=dict( - nx_hexagon=["int", "Number of hexagons (horizontally) to be created"], - agg_func=[ - "function", - "Numpy array aggregator, it must take as input a 1D array", - "and output a scalar value.", - ], - min_count=[ - "int", - "Minimum number of points in a hexagon for it to be displayed.", - "If None and color is not set, display all hexagons.", - "If None and color is set, only display hexagons that contain points.", - ], - show_original_data=[ - "bool", - "Whether to show the original data on top of the hexbin aggregation.", - ], - original_data_marker=["dict", "Scattermapbox marker options."], - ), -)