statannotations package

Subpackages

Submodules

statannotations.Annotation module

class statannotations.Annotation.Annotation(structs, data: Union[str, StatResult], formatter: Optional[Formatter] = None)

Bases: object

Holds data, linked structs and an optional Formatter.

check_data_stat_result()
property formatted_output
print_labels_and_content(sep=' vs. ')
property text

statannotations.Annotator module

class statannotations.Annotator.Annotator(ax, pairs, plot='boxplot', data=None, x=None, y=None, hue=None, order=None, hue_order=None, engine='seaborn', verbose=True, hide_non_significant=False, **plot_params)

Bases: object

Optionally computes statistical test between pairs of data series, and add statistical annotation on top of the groups (boxes, bars…). The same exact arguments provided to the seaborn plotting function must be passed to the constructor.

This Annotator works in one of the three following modes:

  • Add custom text annotations (set_custom_annotations)

  • Format pvalues and add them to the plot (set_pvalues)

  • Perform a statistical test and then add the results to the plot

    (apply_test)

property alpha
annotate(line_offset=None, line_offset_to_group=None)

Add configured annotations to the plot.

annotate_custom_annotations(text_annot_custom)
Parameters:

text_annot_custom – List of strings to annotate for each pair

apply_and_annotate()

Applies a configured statistical test and annotates the plot

apply_test(num_comparisons='auto', **stats_params)
Parameters:

  • stats_params – Parameters for statistical test functions.

  • num_comparisons – Override number of comparisons otherwise calculated with number of pairs

property comparisons_correction
configure(**parameters)

  • alpha: Acceptable type 1 error for statistical tests, default 0.05

  • color

  • comparisons_correction: Method for multiple comparisons correction.

    One of statsmodels multipletests methods (w/ default FWER), or a ComparisonsCorrection instance.

  • correction_format: How to format the star notation on the plot when

    the multiple comparisons correction method removes the significance * default: a ‘ (ns)’ suffix is added, such as in printed output, corresponds to “{star} ({suffix})” * replace: the original star value is replaced with ‘ns’ corresponds to “{suffix}” * a custom formatting string using “{star}” for the original pvalue and ‘{suffix}’ for ‘ns’

  • line_height: in axes fraction coordinates

  • line_offset

  • line_offset_to_group

  • line_width

  • loc

  • pvalue_format: list of lists, or tuples. Default values are:

    • For “star” text_format: [[1e-4, “****”], [1e-3, “***”], [1e-2, “**”], [0.05, “*”], [1, “ns”]].

    • For “simple” text_format: [[1e-5, “1e-5”], [1e-4, “1e-4”], [1e-3, “0.001”], [1e-2, “0.01”], [5e-2, “0.05”]].

  • show_test_name: Set to False to not show the (short) name of

    test

  • test

  • text_offset: in points

  • test_short_name

  • use_fixed_offset

  • verbose

property fig
get_annotations_text()
get_configuration()
static get_empty_annotator()

This instance will have to be initialized with new_plot() before being used. This behavior can be useful to create an Annotator before using it in a FacetGrid mapping.

classmethod get_offset_func(position)
has_type0_comparisons_correction()
property loc
new_plot(ax, pairs=None, plot='boxplot', data=None, x=None, y=None, hue=None, order=None, hue_order=None, engine: str = 'seaborn', **plot_params)
property orient
static plot_and_annotate(plot: str, pairs: list, plot_params: dict, configuration: dict, annotation_func: str, annotation_params: Optional[dict] = None, ax_op_before: Optional[List[Union[str, list, None, dict]]] = None, ax_op_after: Optional[List[Union[str, list, None, dict]]] = None, annotate_params: Optional[dict] = None)

Plots using seaborn and annotates in a single call.

Parameters:

  • plot – seaborn plotting function to call

  • pairs – pairs to compare (see Annotator)

  • plot_params – parameters for plotting function call

  • configuration – parameters for Annotator.configure

  • annotation_func – name of annotation function to be called, from: * ‘set_custom_annotations’ * ‘set_pvalues’ * ‘apply_test’

  • annotation_params – parameters for the annotation function

  • ax_op_before – list of [func_name, args, kwargs] to apply on ax before annotating

  • ax_op_after – list of [func_name, args, kwargs] to apply on ax after annotating

  • annotate_params – parameters for Annotator.annotate

plot_and_annotate_facets(plot: str, plot_params: dict, configuration: dict, annotation_func: str, *args, annotation_params: Optional[dict] = None, ax_op_before: Optional[List[Union[str, list, None, dict]]] = None, ax_op_after: Optional[List[Union[str, list, None, dict]]] = None, annotate_params: Optional[dict] = None, **kwargs)

Plots using seaborn and annotates in a single call, to be used within a FacetGrid. First, initialize the Annotator with Annotator(None, pairs) to define the pairs, then map this function onto the FacetGrid.

Parameters:

  • plot – seaborn plotting function to call

  • plot_params – parameters for plotting function call

  • configuration – parameters for Annotator.configure

  • annotation_func – name of annotation function to be called, from: * ‘set_custom_annotations’ * ‘set_pvalues’ * ‘apply_test’

  • annotation_params – parameters for the annotation function

  • ax_op_before – list of [func_name, args, kwargs] to apply on ax before annotating

  • ax_op_after – list of [func_name, args, kwargs] to apply on ax after annotating

  • annotate_params – parameters for Annotator.annotate

  • args – additional parameters for the seaborn function

  • kwargs – additional parameters for the seaborn function

print_pvalue_legend()
property pvalue_format
reset_configuration()
set_custom_annotations(text_annot_custom)
Parameters:

text_annot_custom – List of strings to annotate for each pair

set_pvalues(pvalues, num_comparisons='auto')
Parameters:

  • pvalues – list or array of p-values for each pair comparison.

  • num_comparisons – Override number of comparisons otherwise calculated with number of pairs

set_pvalues_and_annotate(pvalues, num_comparisons='auto')
property test
validate_test_short_name()
property verbose

statannotations.PValueFormat module

class statannotations.PValueFormat.Formatter

Bases: object

config(*args, **kwargs)
format_data(data)
class statannotations.PValueFormat.PValueFormat

Bases: Formatter

config(**parameters)
property correction_format
format_data(result)
get_configuration()
print_legend_if_used()
property pvalue_format_string
property pvalue_thresholds
property simple_format_string
property text_format
statannotations.PValueFormat.get_corrected_star(star: str, res: StatResult, correction_format='{star} ({suffix})') → str
statannotations.PValueFormat.sort_pvalue_thresholds(pvalue_thresholds)

statannotations.format_annotations module

statannotations.format_annotations.pval_annotation_text(result: List[StatResult], pvalue_thresholds: List) → List[tuple]
Parameters:

  • result – StatResult instance or list thereof

  • pvalue_thresholds – thresholds to use for formatter

Returns:

A List of rendered annotations if a list of StatResults was provided, a string otherwise.

statannotations.format_annotations.simple_text(result: StatResult, pvalue_format, pvalue_thresholds, short_test_name=True) → str

Generates simple text for test name and pvalue.

Parameters:

  • result – StatResult instance

  • pvalue_format – format string for pvalue

  • pvalue_thresholds – String to display per pvalue range

  • short_test_name – whether to display the test (short) name

Returns:

simple annotation

statannotations.utils module

exception statannotations.utils.InvalidParametersError(parameters)

Bases: Exception

statannotations.utils.check_is_in(x, valid_values, error_type=<class 'ValueError'>, label=None)

Raise an error if x is not in valid_values.

statannotations.utils.check_not_none(name, value)
statannotations.utils.check_order_in_data(data, x, order) → None
statannotations.utils.check_pairs_in_data(pairs: Union[list, tuple], data: Optional[Union[List[list], DataFrame]] = None, coord: Optional[Union[str, list]] = None, hue: Optional[str] = None, hue_order: Optional[List[str]] = None)

Checks that values referred to in order and pairs exist in data.

statannotations.utils.check_valid_text_format(text_format)
statannotations.utils.empty_dict_if_none(data)
statannotations.utils.get_closest(a_list, value)

Assumes myList is sorted. Returns closest value to myNumber. If two numbers are equally close, return the smallest number. from https://stackoverflow.com/a/12141511/9981846

statannotations.utils.get_x_values(data, x) → set
statannotations.utils.raise_expected_got(expected, for_, got, error_type=<class 'ValueError'>)

Raise a standardized error message.

Raise an error_type error with the message

Expected expected for for_; got got instead.

Or, if for_ is None,

Expected expected; got got instead.

statannotations.utils.remove_null(series)
statannotations.utils.render_collection(collection)

Module contents