statannotations package
Subpackages
Submodules
statannotations.Annotation module
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, **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)