pyevoc.visualisation.plots#

PyEvoc plotting utilities.

This module consolidates the plotting routines originally developed in the notebook workflow:

  1. EVOC concentric maps;

  2. EVOC semantic trees linking quadrant roots to collocation leaves;

  3. emoji EVOC Plotly maps;

  4. temporal EVOC Sankey diagrams.

The functions intentionally preserve the visual logic and default parameters of the original notebook outputs while exposing a package-ready API.

pyevoc.visualisation.plots.build_evoc_target_plot(evoc_quadrants_df, upos, pos_thresholds_round_df, top_n_per_quadrant=20, output_dir=OUTPUT_DIR, figsize=(9.5, 8), dpi=600, node_size_mode=NODE_SIZE_MODE, fixed_node_size=FIXED_NODE_SIZE, concreteness_size_min=CONCRETENESS_SIZE_MIN, concreteness_size_max=CONCRETENESS_SIZE_MAX, sd_multiplier=1.0, random_state=RANDOM_STATE)[source]#

Build the original notebook-style EVOC concentric map.

pyevoc.visualisation.plots.build_evoc_collocation_tree_for_upos(evoc_quadrants_df, collocations_df, tokens_df, upos, output_dir=OUTPUT_DIR, top_roots_per_quadrant=TOP_ROOTS_PER_QUADRANT, max_leaves_per_root=MAX_LEAVES_PER_ROOT, min_leaf_freq=MIN_LEAF_FREQ, seed=LAYOUT_SEED, width=TREE_FIG_WIDTH, height=TREE_FIG_HEIGHT, png_scale=PNG_SCALE, show_diagnostics=False)[source]#

Build and save the full EVOC semantic collocation tree for a UPOS tag.

Orchestrates root selection, leaf preparation, graph construction, layout, and Plotly rendering. Saves both HTML and PNG outputs to output_dir.

Parameters:

  • evoc_quadrants_df – EVOC quadrants DataFrame.

  • collocations_df – Raw collocation DataFrame.

  • tokens_df – Token-level DataFrame used for user counts.

  • upos – Universal POS tag to visualise (e.g. "NOUN").

  • output_dir – Directory for saved figures.

  • top_roots_per_quadrant – Maximum root terms per quadrant.

  • max_leaves_per_root – Maximum collocation leaves per root.

  • min_leaf_freq – Minimum frequency threshold for leaf collocations.

  • seed – Layout RNG seed.

  • width – Figure width in pixels.

  • height – Figure height in pixels.

  • png_scale – Resolution scale factor for PNG export.

  • show_diagnostics – If True, display the diagnostics DataFrame in an interactive environment (uses display if available, otherwise print).

Returns:

A dict with keys fig, graph, positions, quadrant_y, row_top, row_bottom, line_counts, row_heights, roots_df, leaves_df, edges_df, diagnostics_df, html, and png.

pyevoc.visualisation.plots.build_emoji_evoc_plot(html_file=EMOJI_HTML_FILE, output_dir=OUTPUT_DIR, output_html=EMOJI_OUTPUT_HTML, output_png=EMOJI_OUTPUT_PNG, top_n_per_quadrant=TOP_N_PER_QUADRANT, width=EMOJI_FIG_WIDTH, height=EMOJI_FIG_HEIGHT, pad_salience=EMOJI_AXIS_PAD_SALIENCE, pad_diffusion=EMOJI_AXIS_PAD_DIFFUSION, show=False)[source]#

Build and save the emoji EVOC Plotly scatter map.

Parses an EVOC compact HTML report, selects the top emojis per quadrant, computes label positions, adds AFE/AOE threshold lines, and writes both an interactive HTML file and an optional PNG.

Parameters:

  • html_file – Path to the source EVOC compact HTML report.

  • output_dir – Directory for saved figures.

  • output_html – Filename (not path) for the output HTML file.

  • output_png – Filename (not path) for the output PNG file, or None to skip PNG export.

  • top_n_per_quadrant – Maximum emojis to display per quadrant.

  • width – Figure width in pixels.

  • height – Figure height in pixels.

  • pad_salience – Axis padding added to the salience (x) range.

  • pad_diffusion – Axis padding added to the diffusion (y) range.

  • show – If True, call fig.show() after saving.

Returns:

A tuple (fig, df, html_out) where fig is the Plotly figure, df is the plotted emoji DataFrame (with x_range and y_range stored in df.attrs), and html_out is the path to the saved HTML file.

Raises:

  • ImportError – If plotly is not installed.

  • ValueError – If AFE/AOE thresholds cannot be extracted from html_file.

pyevoc.visualisation.plots.build_temporal_sankey_ordered(period_quadrants, output_dir=OUTPUT_DIR, output_html='temporal_evoc_sankey_ordered.html', output_png='temporal_evoc_sankey_ordered.png', period_col='period', term_col='term', quadrant_col='quadrant', quadrant_order=QUADRANT_ORDER_WITH_ABSENT, quadrant_colours=SANKEY_QUADRANT_COLOURS, width=1700, height=900, node_thickness=22, node_pad=18, arrangement='fixed', link_alpha=LINK_ALPHA, show_zero_nodes=True, top_margin_y=0.015, bottom_margin_y=0.015, min_vertical_gap=0.018, min_node_height=0.018, export_png=True, png_scale=4, show=False)[source]#

Build a value-aware, order-preserving temporal EVOC Sankey.

Period labels are taken directly from period_quadrants[period_col]. If the column is categorical, its category order is used; otherwise first occurrence order is preserved. This is compatible with the labels produced by run_temporal_stability_analysis.

pyevoc.visualisation.plots.select_terms_for_target(df, top_n_per_quadrant)[source]#

Select the top n terms per quadrant for the concentric map.

Terms are ranked by quadrant-specific criteria: high-salience quadrants (Central nucleus, First periphery) prioritise relative diffusion; the Contrast zone prioritises rank; the Peripheral system prioritises diffusion then rank.

Parameters:

  • df – EVOC quadrants DataFrame containing relative_diffusion, Rank, frequency, and quadrant columns.

  • top_n_per_quadrant – Maximum number of terms to retain per quadrant.

Returns:

A concatenated DataFrame of selected terms.

Raises:

ValueError – If any required column is missing from df.

pyevoc.visualisation.plots.assign_target_coordinates(plot_df, node_size_mode=NODE_SIZE_MODE, fixed_node_size=FIXED_NODE_SIZE, concreteness_size_min=CONCRETENESS_SIZE_MIN, concreteness_size_max=CONCRETENESS_SIZE_MAX, random_state=RANDOM_STATE)[source]#

Compute polar and Cartesian coordinates for every term in plot_df.

Assigns each term a radius (from Rank), an angular position (from relative diffusion within its quadrant), and small random jitter. Adds radius, theta, x, y, and point_size columns to the returned DataFrame.

Parameters:

  • plot_df – DataFrame of selected terms with Rank, relative_diffusion, and quadrant columns.

  • node_size_mode – Passed to compute_node_sizes().

  • fixed_node_size – Passed to compute_node_sizes().

  • concreteness_size_min – Passed to compute_node_sizes().

  • concreteness_size_max – Passed to compute_node_sizes().

  • random_state – Seed for the NumPy random generator used for jitter.

Returns:

A copy of plot_df with coordinate and size columns appended.

pyevoc.visualisation.plots.parse_emoji_evoc_html(html_file)[source]#

Parse an EVOC compact HTML report and extract emoji quadrant data.

Reads .quad-card elements from the HTML, extracting one row per emoji entry with relative diffusion, frequency, rank, description, and quadrant.

Parameters:

html_file – Path to the compact EVOC HTML report.

Returns:

A DataFrame with columns emoji, relative_diffusion, frequency, rank, description, quadrant, and salience.

Raises:

  • ImportError – If beautifulsoup4 is not installed.

  • ValueError – If no emoji records are found in the file.

pyevoc.visualisation.plots.select_emojis_for_plot(df, top_n_per_quadrant=TOP_N_PER_QUADRANT)[source]#

Select the top n emojis per quadrant for the Plotly scatter map.

Uses the same quadrant-specific ranking logic as select_terms_for_target() (diffusion / rank / frequency priority varies by quadrant).

Parameters:

  • df – Parsed emoji DataFrame from parse_emoji_evoc_html().

  • top_n_per_quadrant – Maximum emojis to keep per quadrant. Pass None to keep all.

Returns:

A concatenated DataFrame of selected emojis.

Raises:

ValueError – If no emojis are selected.