pyevoc.visualisation#

Publication-oriented and interactive plots for EVOC maps, semantic trees, emojis, and temporal Sankey flows.

PyEvoc visualisation layer.

This subpackage exposes plotting functions for EVOC concentric maps, semantic trees, emoji EVOC maps and temporal Sankey diagrams. Plotting dependencies are kept local to the plotting module; this wrapper loads public names lazily.

pyevoc.visualisation.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.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.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.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.

Modules#