You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
345 lines
8.8 KiB
345 lines
8.8 KiB
1 year ago
|
"""
|
||
|
|
This type stub file was generated by pyright.
|
||
|
|
"""
|
||
|
|
|
||
|
|
"""Utility functions, mostly for internal use."""
|
||
|
|
__all__ = ["desaturate", "saturate", "set_hls_values", "despine", "get_dataset_names", "get_data_home", "load_dataset"]
|
||
|
|
def sort_df(df, *args, **kwargs):
|
||
|
|
"""Wrapper to handle different pandas sorting API pre/post 0.17."""
|
||
|
|
...
|
||
|
|
|
||
|
|
def ci_to_errsize(cis, heights): # -> NDArray[Unknown]:
|
||
|
|
"""Convert intervals to error arguments relative to plot heights.
|
||
|
|
|
||
|
|
Parameters
|
||
|
|
----------
|
||
|
|
cis: 2 x n sequence
|
||
|
|
sequence of confidence interval limits
|
||
|
|
heights : n sequence
|
||
|
|
sequence of plot heights
|
||
|
|
|
||
|
|
Returns
|
||
|
|
-------
|
||
|
|
errsize : 2 x n array
|
||
|
|
sequence of error size relative to height values in correct
|
||
|
|
format as argument for plt.bar
|
||
|
|
|
||
|
|
"""
|
||
|
|
...
|
||
|
|
|
||
|
|
def pmf_hist(a, bins=...): # -> tuple[ndarray[Any, dtype[Any]], Any, Any]:
|
||
|
|
"""Return arguments to plt.bar for pmf-like histogram of an array.
|
||
|
|
|
||
|
|
DEPRECATED: will be removed in a future version.
|
||
|
|
|
||
|
|
Parameters
|
||
|
|
----------
|
||
|
|
a: array-like
|
||
|
|
array to make histogram of
|
||
|
|
bins: int
|
||
|
|
number of bins
|
||
|
|
|
||
|
|
Returns
|
||
|
|
-------
|
||
|
|
x: array
|
||
|
|
left x position of bars
|
||
|
|
h: array
|
||
|
|
height of bars
|
||
|
|
w: float
|
||
|
|
width of bars
|
||
|
|
|
||
|
|
"""
|
||
|
|
...
|
||
|
|
|
||
|
|
def desaturate(color, prop): # -> tuple[float, float, float]:
|
||
|
|
"""Decrease the saturation channel of a color by some percent.
|
||
|
|
|
||
|
|
Parameters
|
||
|
|
----------
|
||
|
|
color : matplotlib color
|
||
|
|
hex, rgb-tuple, or html color name
|
||
|
|
prop : float
|
||
|
|
saturation channel of color will be multiplied by this value
|
||
|
|
|
||
|
|
Returns
|
||
|
|
-------
|
||
|
|
new_color : rgb tuple
|
||
|
|
desaturated color code in RGB tuple representation
|
||
|
|
|
||
|
|
"""
|
||
|
|
...
|
||
|
|
|
||
|
|
def saturate(color): # -> tuple[float, float, float]:
|
||
|
|
"""Return a fully saturated color with the same hue.
|
||
|
|
|
||
|
|
Parameters
|
||
|
|
----------
|
||
|
|
color : matplotlib color
|
||
|
|
hex, rgb-tuple, or html color name
|
||
|
|
|
||
|
|
Returns
|
||
|
|
-------
|
||
|
|
new_color : rgb tuple
|
||
|
|
saturated color code in RGB tuple representation
|
||
|
|
|
||
|
|
"""
|
||
|
|
...
|
||
|
|
|
||
|
|
def set_hls_values(color, h=..., l=..., s=...): # -> tuple[float, float, float]:
|
||
|
|
"""Independently manipulate the h, l, or s channels of a color.
|
||
|
|
|
||
|
|
Parameters
|
||
|
|
----------
|
||
|
|
color : matplotlib color
|
||
|
|
hex, rgb-tuple, or html color name
|
||
|
|
h, l, s : floats between 0 and 1, or None
|
||
|
|
new values for each channel in hls space
|
||
|
|
|
||
|
|
Returns
|
||
|
|
-------
|
||
|
|
new_color : rgb tuple
|
||
|
|
new color code in RGB tuple representation
|
||
|
|
|
||
|
|
"""
|
||
|
|
...
|
||
|
|
|
||
|
|
def axlabel(xlabel, ylabel, **kwargs): # -> None:
|
||
|
|
"""Grab current axis and label it.
|
||
|
|
|
||
|
|
DEPRECATED: will be removed in a future version.
|
||
|
|
|
||
|
|
"""
|
||
|
|
...
|
||
|
|
|
||
|
|
def remove_na(vector):
|
||
|
|
"""Helper method for removing null values from data vectors.
|
||
|
|
|
||
|
|
Parameters
|
||
|
|
----------
|
||
|
|
vector : vector object
|
||
|
|
Must implement boolean masking with [] subscript syntax.
|
||
|
|
|
||
|
|
Returns
|
||
|
|
-------
|
||
|
|
clean_clean : same type as ``vector``
|
||
|
|
Vector of data with null values removed. May be a copy or a view.
|
||
|
|
|
||
|
|
"""
|
||
|
|
...
|
||
|
|
|
||
|
|
def get_color_cycle(): # -> Any | list[str]:
|
||
|
|
"""Return the list of colors in the current matplotlib color cycle
|
||
|
|
|
||
|
|
Parameters
|
||
|
|
----------
|
||
|
|
None
|
||
|
|
|
||
|
|
Returns
|
||
|
|
-------
|
||
|
|
colors : list
|
||
|
|
List of matplotlib colors in the current cycle, or dark gray if
|
||
|
|
the current color cycle is empty.
|
||
|
|
"""
|
||
|
|
...
|
||
|
|
|
||
|
|
def despine(fig=..., ax=..., top=..., right=..., left=..., bottom=..., offset=..., trim=...): # -> None:
|
||
|
|
"""Remove the top and right spines from plot(s).
|
||
|
|
|
||
|
|
fig : matplotlib figure, optional
|
||
|
|
Figure to despine all axes of, defaults to the current figure.
|
||
|
|
ax : matplotlib axes, optional
|
||
|
|
Specific axes object to despine. Ignored if fig is provided.
|
||
|
|
top, right, left, bottom : boolean, optional
|
||
|
|
If True, remove that spine.
|
||
|
|
offset : int or dict, optional
|
||
|
|
Absolute distance, in points, spines should be moved away
|
||
|
|
from the axes (negative values move spines inward). A single value
|
||
|
|
applies to all spines; a dict can be used to set offset values per
|
||
|
|
side.
|
||
|
|
trim : bool, optional
|
||
|
|
If True, limit spines to the smallest and largest major tick
|
||
|
|
on each non-despined axis.
|
||
|
|
|
||
|
|
Returns
|
||
|
|
-------
|
||
|
|
None
|
||
|
|
|
||
|
|
"""
|
||
|
|
...
|
||
|
|
|
||
|
|
def percentiles(a, pcts, axis=...): # -> ndarray[Any, dtype[Unknown]]:
|
||
|
|
"""Like scoreatpercentile but can take and return array of percentiles.
|
||
|
|
|
||
|
|
DEPRECATED: will be removed in a future version.
|
||
|
|
|
||
|
|
Parameters
|
||
|
|
----------
|
||
|
|
a : array
|
||
|
|
data
|
||
|
|
pcts : sequence of percentile values
|
||
|
|
percentile or percentiles to find score at
|
||
|
|
axis : int or None
|
||
|
|
if not None, computes scores over this axis
|
||
|
|
|
||
|
|
Returns
|
||
|
|
-------
|
||
|
|
scores: array
|
||
|
|
array of scores at requested percentiles
|
||
|
|
first dimension is length of object passed to ``pcts``
|
||
|
|
|
||
|
|
"""
|
||
|
|
...
|
||
|
|
|
||
|
|
def ci(a, which=..., axis=...):
|
||
|
|
"""Return a percentile range from an array of values."""
|
||
|
|
...
|
||
|
|
|
||
|
|
def sig_stars(p): # -> Literal['***', '**', '*', '.', '']:
|
||
|
|
"""Return a R-style significance string corresponding to p values.
|
||
|
|
|
||
|
|
DEPRECATED: will be removed in a future version.
|
||
|
|
|
||
|
|
"""
|
||
|
|
...
|
||
|
|
|
||
|
|
def iqr(a): # -> float | NDArray[floating[Any]] | Any | NDArray[Any]:
|
||
|
|
"""Calculate the IQR for an array of numbers.
|
||
|
|
|
||
|
|
DEPRECATED: will be removed in a future version.
|
||
|
|
|
||
|
|
"""
|
||
|
|
...
|
||
|
|
|
||
|
|
def get_dataset_names(): # -> list[Any]:
|
||
|
|
"""Report available example datasets, useful for reporting issues.
|
||
|
|
|
||
|
|
Requires an internet connection.
|
||
|
|
|
||
|
|
"""
|
||
|
|
...
|
||
|
|
|
||
|
|
def get_data_home(data_home=...): # -> str:
|
||
|
|
"""Return a path to the cache directory for example datasets.
|
||
|
|
|
||
|
|
This directory is then used by :func:`load_dataset`.
|
||
|
|
|
||
|
|
If the ``data_home`` argument is not specified, it tries to read from the
|
||
|
|
``SEABORN_DATA`` environment variable and defaults to ``~/seaborn-data``.
|
||
|
|
|
||
|
|
"""
|
||
|
|
...
|
||
|
|
|
||
|
|
def load_dataset(name, cache=..., data_home=..., **kws):
|
||
|
|
"""Load an example dataset from the online repository (requires internet).
|
||
|
|
|
||
|
|
This function provides quick access to a small number of example datasets
|
||
|
|
that are useful for documenting seaborn or generating reproducible examples
|
||
|
|
for bug reports. It is not necessary for normal usage.
|
||
|
|
|
||
|
|
Note that some of the datasets have a small amount of preprocessing applied
|
||
|
|
to define a proper ordering for categorical variables.
|
||
|
|
|
||
|
|
Use :func:`get_dataset_names` to see a list of available datasets.
|
||
|
|
|
||
|
|
Parameters
|
||
|
|
----------
|
||
|
|
name : str
|
||
|
|
Name of the dataset (``{name}.csv`` on
|
||
|
|
https://github.com/mwaskom/seaborn-data).
|
||
|
|
cache : boolean, optional
|
||
|
|
If True, try to load from the local cache first, and save to the cache
|
||
|
|
if a download is required.
|
||
|
|
data_home : string, optional
|
||
|
|
The directory in which to cache data; see :func:`get_data_home`.
|
||
|
|
kws : keys and values, optional
|
||
|
|
Additional keyword arguments are passed to passed through to
|
||
|
|
:func:`pandas.read_csv`.
|
||
|
|
|
||
|
|
Returns
|
||
|
|
-------
|
||
|
|
df : :class:`pandas.DataFrame`
|
||
|
|
Tabular data, possibly with some preprocessing applied.
|
||
|
|
|
||
|
|
"""
|
||
|
|
...
|
||
|
|
|
||
|
|
def axis_ticklabels_overlap(labels): # -> Literal[False]:
|
||
|
|
"""Return a boolean for whether the list of ticklabels have overlaps.
|
||
|
|
|
||
|
|
Parameters
|
||
|
|
----------
|
||
|
|
labels : list of matplotlib ticklabels
|
||
|
|
|
||
|
|
Returns
|
||
|
|
-------
|
||
|
|
overlap : boolean
|
||
|
|
True if any of the labels overlap.
|
||
|
|
|
||
|
|
"""
|
||
|
|
...
|
||
|
|
|
||
|
|
def axes_ticklabels_overlap(ax): # -> tuple[Unknown | Literal[False], Unknown | Literal[False]]:
|
||
|
|
"""Return booleans for whether the x and y ticklabels on an Axes overlap.
|
||
|
|
|
||
|
|
Parameters
|
||
|
|
----------
|
||
|
|
ax : matplotlib Axes
|
||
|
|
|
||
|
|
Returns
|
||
|
|
-------
|
||
|
|
x_overlap, y_overlap : booleans
|
||
|
|
True when the labels on that axis overlap.
|
||
|
|
|
||
|
|
"""
|
||
|
|
...
|
||
|
|
|
||
|
|
def locator_to_legend_entries(locator, limits, dtype): # -> tuple[list[Unknown], list[Unknown]]:
|
||
|
|
"""Return levels and formatted levels for brief numeric legends."""
|
||
|
|
class dummy_axis:
|
||
|
|
...
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
def relative_luminance(color): # -> Any:
|
||
|
|
"""Calculate the relative luminance of a color according to W3C standards
|
||
|
|
|
||
|
|
Parameters
|
||
|
|
----------
|
||
|
|
color : matplotlib color or sequence of matplotlib colors
|
||
|
|
Hex code, rgb-tuple, or html color name.
|
||
|
|
|
||
|
|
Returns
|
||
|
|
-------
|
||
|
|
luminance : float(s) between 0 and 1
|
||
|
|
|
||
|
|
"""
|
||
|
|
...
|
||
|
|
|
||
|
|
def to_utf8(obj): # -> str:
|
||
|
|
"""Return a string representing a Python object.
|
||
|
|
|
||
|
|
Strings (i.e. type ``str``) are returned unchanged.
|
||
|
|
|
||
|
|
Byte strings (i.e. type ``bytes``) are returned as UTF-8-decoded strings.
|
||
|
|
|
||
|
|
For other objects, the method ``__str__()`` is called, and the result is
|
||
|
|
returned as a string.
|
||
|
|
|
||
|
|
Parameters
|
||
|
|
----------
|
||
|
|
obj : object
|
||
|
|
Any Python object
|
||
|
|
|
||
|
|
Returns
|
||
|
|
-------
|
||
|
|
s : str
|
||
|
|
UTF-8-decoded string representation of ``obj``
|
||
|
|
|
||
|
|
"""
|
||
|
|
...
|
||
|
|
|
||
|
|
def adjust_legend_subtitles(legend): # -> None:
|
||
|
|
"""Make invisible-handle "subtitles" entries look more like titles."""
|
||
|
|
...
|
||
|
|
|