pyevoc.analysis.quadrants#

EVOC thresholding, quadrant assignment, and compact HTML reporting.

This module assigns terms to the four classical EVOC/HEM quadrants after term-level statistics, concreteness labelling, and emoji description labelling have been computed.

The module implements the EVOC-ready logic used in PyEvoc:

  • optional minimal-frequency filtering;

  • POS-specific AFE and AOE thresholds;

  • user-level or document-level relative diffusion;

  • rounded comparison values for stable table construction;

  • diffusion/salience classes;

  • ordered quadrant labels;

  • publication-ready EVOC table;

  • threshold and quadrant diagnostics;

  • optional compact HTML reports by UPOS category.

The expected input is a term-level dataframe containing at least:

  • term

  • upos

  • term_type

  • n_docs or n_posts

  • n_users

  • R_pos

  • R_struct

  • S

  • Rank

  • freq_for_quadrant

  • user_penetration

  • posts_per_user

Optional enrichment columns such as concreteness_label and emoji_description are preserved when available.

class pyevoc.analysis.quadrants.QuadrantConfig(minimal_freq=2, round_digits=2, focal_upos=<factory>, quadrant_order=<factory>, diffusion_basis='user_penetration', term_col='term', upos_col='upos', term_type_col='term_type', n_docs_col='n_docs', n_posts_col='n_posts', n_users_col='n_users', r_pos_col='R_pos', r_struct_col='R_struct', salience_col='S', rank_col='Rank', freq_col='freq_for_quadrant', user_penetration_col='user_penetration', document_penetration_col='document_penetration', post_penetration_col='post_penetration', posts_per_user_col='posts_per_user', concreteness_score_col='concreteness_score', concreteness_label_col='concreteness_label', concreteness_in_lexicon_col='concreteness_in_lexicon', emoji_description_col='emoji_description', human_readable=True, generate_html=False, html_output_dir='evoc_outputs', html_top_n=20, html_max_width_px=950, verbose=True)[source]#

Bases: object

Configuration for EVOC quadrant assignment and optional HTML reporting.

Parameters:

  • minimal_freq (int)

  • round_digits (int)

  • focal_upos (set[str])

  • quadrant_order (list[str])

  • diffusion_basis (str)

  • term_col (str)

  • upos_col (str)

  • term_type_col (str)

  • n_docs_col (str)

  • n_posts_col (str)

  • n_users_col (str)

  • r_pos_col (str)

  • r_struct_col (str)

  • salience_col (str)

  • rank_col (str)

  • freq_col (str)

  • user_penetration_col (str)

  • document_penetration_col (str)

  • post_penetration_col (str)

  • posts_per_user_col (str)

  • concreteness_score_col (str)

  • concreteness_label_col (str)

  • concreteness_in_lexicon_col (str)

  • emoji_description_col (str)

  • human_readable (bool)

  • generate_html (bool)

  • html_output_dir (str | Path)

  • html_top_n (int)

  • html_max_width_px (int)

  • verbose (bool)

minimal_freq: int = 2#
round_digits: int = 2#
focal_upos: set[str]#
quadrant_order: list[str]#
diffusion_basis: str = 'user_penetration'#
term_col: str = 'term'#
upos_col: str = 'upos'#
term_type_col: str = 'term_type'#
n_docs_col: str = 'n_docs'#
n_posts_col: str = 'n_posts'#
n_users_col: str = 'n_users'#
r_pos_col: str = 'R_pos'#
r_struct_col: str = 'R_struct'#
salience_col: str = 'S'#
rank_col: str = 'Rank'#
freq_col: str = 'freq_for_quadrant'#
user_penetration_col: str = 'user_penetration'#
document_penetration_col: str = 'document_penetration'#
post_penetration_col: str = 'post_penetration'#
posts_per_user_col: str = 'posts_per_user'#
concreteness_score_col: str = 'concreteness_score'#
concreteness_label_col: str = 'concreteness_label'#
concreteness_in_lexicon_col: str = 'concreteness_in_lexicon'#
emoji_description_col: str = 'emoji_description'#
human_readable: bool = True#
generate_html: bool = False#
html_output_dir: str | Path = 'evoc_outputs'#
html_top_n: int = 20#
html_max_width_px: int = 950#
verbose: bool = True#
pyevoc.analysis.quadrants.format_value(value, digits=2)[source]#

Format a numeric value for EVOC compact HTML tables.

Parameters:
Return type:

str

pyevoc.analysis.quadrants.format_int(value)[source]#

Format an integer-like value for EVOC compact HTML tables.

Parameters:

value (object)

Return type:

str

pyevoc.analysis.quadrants.concreteness_class(label)[source]#

Return a CSS class for a concreteness label.

Parameters:

label (object)

Return type:

str

pyevoc.analysis.quadrants.get_threshold_values(pos_thresholds_round_df, upos)[source]#

Return formatted AFE/AOE threshold values for one UPOS category.

Parameters:

  • pos_thresholds_round_df (DataFrame)

  • upos (str)

Return type:

tuple[str, str]

pyevoc.analysis.quadrants.quadrant_rule_label(quadrant, afe, aoe)[source]#

Return the rule label printed under each quadrant title.

Parameters:
Return type:

str

pyevoc.analysis.quadrants.select_top_terms(df, quadrant, top_n=20)[source]#

Select the top terms for one quadrant using the legacy EVOC ordering.

Parameters:

  • df (DataFrame)

  • quadrant (str)

  • top_n (int)

Return type:

DataFrame

pyevoc.analysis.quadrants.build_quadrant_block(df, quadrant, upos, afe, aoe, top_n=20)[source]#

Build one HTML card for a given quadrant and UPOS category.

Parameters:
Return type:

str

pyevoc.analysis.quadrants.build_evoc_html_for_upos(evoc_quadrants_df, upos, pos_thresholds_round_df, *, output_dir='evoc_outputs', top_n=20, max_width_px=950)[source]#

Write the compact EVOC HTML report for one UPOS category.

Parameters:

  • evoc_quadrants_df (DataFrame)

  • upos (str)

  • pos_thresholds_round_df (DataFrame)

  • output_dir (str | Path)

  • top_n (int)

  • max_width_px (int)

Return type:

str

pyevoc.analysis.quadrants.generate_evoc_html_reports(evoc_quadrants_df, pos_thresholds_round_df, *, output_dir='evoc_outputs', top_n=20, max_width_px=950, upos_values=None)[source]#

Generate compact EVOC HTML reports for the requested UPOS categories.

Parameters:

  • evoc_quadrants_df (DataFrame)

  • pos_thresholds_round_df (DataFrame)

  • output_dir (str | Path)

  • top_n (int)

  • max_width_px (int)

  • upos_values (list[str] | tuple[str, ...] | None)

Return type:

dict[str, str]

pyevoc.analysis.quadrants.assign_evoc_quadrants(term_stats_df, *, minimal_freq=2, focal_upos=None, quadrant_order=None, round_digits=2, diffusion_basis='user_penetration', generate_html=False, html_output_dir='evoc_outputs', html_top_n=20, html_max_width_px=950, config=None)[source]#

Assign EVOC quadrants using relative AFE and mean AOE thresholds.

Parameters:

  • term_stats_df (DataFrame) – Term-level dataframe.

  • minimal_freq (int) – Minimal absolute frequency used to retain terms for quadrant assignment.

  • focal_upos (set[str] | None) – POS categories retained for EVOC assignment.

  • quadrant_order (list[str] | None) – Ordered quadrant labels.

  • round_digits (int) – Number of digits used for rounded threshold comparisons.

  • diffusion_basis (str) – Relative diffusion variable used to compute AFE thresholds. Supported values are user_penetration, document_penetration, post_penetration and diffusion_penetration.

  • generate_html (bool) – If True, write compact EVOC HTML reports by UPOS category.

  • html_output_dir (str | Path) – Directory where HTML files are written.

  • html_top_n (int) – Number of terms displayed in each quadrant card.

  • html_max_width_px (int) – Maximum width of the generated HTML page.

  • config (QuadrantConfig | None) – Optional complete configuration. If supplied, explicit keyword arguments above are ignored unless they are already encoded in config.

Returns:

evoc_quadrants_df, quadrant_counts_df and pos_thresholds_round_df.

Return type:

tuple[pandas.DataFrame, pandas.DataFrame, pandas.DataFrame]

Notes

For backward compatibility, the function always returns three objects. When HTML reports are generated, their paths are stored in evoc_quadrants_df.attrs["html_outputs"].

pyevoc.analysis.quadrants.assign_quadrants(term_stats_df, *, config=None)[source]#

Alias for assign_evoc_quadrants.

Parameters:
Return type:

tuple[DataFrame, DataFrame, DataFrame]

pyevoc.analysis.quadrants.quadrant_summary_by_pos(evoc_quadrants_df, *, upos_col='upos', quadrant_col='quadrant')[source]#

Return quadrant counts by UPOS category.

Parameters:

  • evoc_quadrants_df (DataFrame)

  • upos_col (str)

  • quadrant_col (str)

Return type:

DataFrame