pyevoc.analysis.temporal_stability#

Temporal stability and quadrant mobility for PyEvoc.

This module reconstructs temporal EVOC/HEM dynamics from token-level data and a reference EVOC quadrant table.

It supports three main periodisation strategies:

  • custom: user-supplied cuts or breaks;

  • equal_days / equal_width: periods with approximately equal calendar duration;

  • equal_posts / equal_count: periods with approximately equal numbers of posts/documents.

The module computes:

  • period-specific term quadrants;

  • stable nucleus terms;

  • volatile core terms;

  • quadrant mobility and stability indices;

  • transition diagnostics;

  • temporal engagement diagnostics;

  • optional HTML report.

The implementation is compatible with the rebuilt PyEvoc package schema (doc_id) and with the original notebook schema (post_id).

class pyevoc.analysis.temporal_stability.TemporalStabilityConfig(n_periods=4, time_period_mode='equal_posts', custom_time_breaks=None, custom_time_cuts=None, period_labels=None, right=True, alpha=0.5, max_rank_value=5.0, use_users_for_frequency=True, focal_upos=<factory>, round_digits=2, diffusion_multiplier=100.0, time_col='time', doc_col='doc_id', user_col='user_id', term_col='term', upos_col='upos', r_pos_col='r_pos', r_str_col='r_str', expected_min_timestamp=None, expected_max_timestamp=None, warn_on_time_range_mismatch=False, output_dir='evoc_outputs', write_html_report=True, show_tables=False, verbose=True)[source]#

Bases: object

Configuration for temporal stability analysis.

Parameters:

  • n_periods (int)

  • time_period_mode (str)

  • custom_time_breaks (list[str] | None)

  • custom_time_cuts (list[str] | None)

  • period_labels (list[str] | None)

  • right (bool)

  • alpha (float)

  • max_rank_value (float)

  • use_users_for_frequency (bool)

  • focal_upos (list[str])

  • round_digits (int)

  • diffusion_multiplier (float)

  • time_col (str)

  • doc_col (str)

  • user_col (str)

  • term_col (str)

  • upos_col (str)

  • r_pos_col (str)

  • r_str_col (str)

  • expected_min_timestamp (str | None)

  • expected_max_timestamp (str | None)

  • warn_on_time_range_mismatch (bool)

  • output_dir (str | Path)

  • write_html_report (bool)

  • show_tables (bool)

  • verbose (bool)

n_periods: int = 4#
time_period_mode: str = 'equal_posts'#
custom_time_breaks: list[str] | None = None#
custom_time_cuts: list[str] | None = None#
period_labels: list[str] | None = None#
right: bool = True#
alpha: float = 0.5#
max_rank_value: float = 5.0#
use_users_for_frequency: bool = True#
focal_upos: list[str]#
round_digits: int = 2#
diffusion_multiplier: float = 100.0#
time_col: str = 'time'#
doc_col: str = 'doc_id'#
user_col: str = 'user_id'#
term_col: str = 'term'#
upos_col: str = 'upos'#
r_pos_col: str = 'r_pos'#
r_str_col: str = 'r_str'#
expected_min_timestamp: str | None = None#
expected_max_timestamp: str | None = None#
warn_on_time_range_mismatch: bool = False#
output_dir: str | Path = 'evoc_outputs'#
write_html_report: bool = True#
show_tables: bool = False#
verbose: bool = True#
pyevoc.analysis.temporal_stability.format_float(x, digits=3)[source]#

Format a float for reporting.

Parameters:
Return type:

str

pyevoc.analysis.temporal_stability.format_int(x)[source]#

Format an integer for reporting.

Parameters:

x (object)

Return type:

str

pyevoc.analysis.temporal_stability.quadrant_entropy(x)[source]#

Compute entropy of quadrant memberships.

Parameters:

x (Series | list[object])

Return type:

float

pyevoc.analysis.temporal_stability.gini_coefficient(x)[source]#

Compute the Gini coefficient.

Parameters:

x (ndarray | list[float])

Return type:

float

pyevoc.analysis.temporal_stability.safe_std(x, ddof=1)[source]#

Return standard deviation with safe handling of degenerate inputs.

Parameters:
Return type:

float

pyevoc.analysis.temporal_stability.safe_spearman(x, y)[source]#

Compute Spearman correlation with safe handling of constants.

Parameters:
Return type:

float

pyevoc.analysis.temporal_stability.quarter_label_from_timestamp(ts)[source]#

Return a quarterly label from a timestamp.

Parameters:

ts (object)

Return type:

str

pyevoc.analysis.temporal_stability.quarter_start_utc(ts)[source]#

Return the UTC start of the quarter containing ts.

Parameters:

ts (object)

Return type:

Timestamp

pyevoc.analysis.temporal_stability.next_quarter_start_utc(ts)[source]#

Return the UTC start of the next quarter after ts.

Parameters:

ts (object)

Return type:

Timestamp

pyevoc.analysis.temporal_stability.validate_time_range(observed_min, observed_max, expected_min=None, expected_max=None)[source]#

Compare observed and expected time ranges.

Parameters:
Return type:

dict[str, object]

pyevoc.analysis.temporal_stability.normalise_threshold_table(pos_thresholds_round_df=None, evoc_quadrants_df=None, *, round_digits=2)[source]#

Return internal POS-specific thresholds with exact and rounded columns.

Parameters:

  • pos_thresholds_round_df (DataFrame | None)

  • evoc_quadrants_df (DataFrame | None)

  • round_digits (int)

Return type:

DataFrame

pyevoc.analysis.temporal_stability.build_threshold_display_table(thresholds)[source]#

Return a display-ready threshold table.

Parameters:

thresholds (DataFrame)

Return type:

DataFrame

pyevoc.analysis.temporal_stability.build_time_periods(df, *, time_col='time', doc_col='doc_id', user_col='user_id', n_periods=4, mode='equal_posts', custom_time_breaks=None, custom_time_cuts=None, period_labels=None, right=True, time_range_reference_df=None, expected_min_timestamp=None, expected_max_timestamp=None, warn_on_time_range_mismatch=False)[source]#

Assign observations to temporal periods.

Supported modes#

custom

Use user-defined breaks or internal cuts.

equal_days or equal_width

Generate periods with approximately equal calendar duration.

equal_posts or equal_count

Generate periods with approximately equal numbers of unique posts.

quarters

Generate calendar-quarter periods.

Parameters:

  • df (DataFrame)

  • time_col (str)

  • doc_col (str)

  • user_col (str)

  • n_periods (int)

  • mode (str)

  • custom_time_breaks (list[str] | None)

  • custom_time_cuts (list[str] | None)

  • period_labels (list[str] | None)

  • right (bool)

  • time_range_reference_df (DataFrame | None)

  • expected_min_timestamp (object | None)

  • expected_max_timestamp (object | None)

  • warn_on_time_range_mismatch (bool)

Return type:

tuple[DataFrame, DataFrame, list[Timestamp], dict[str, object]]

pyevoc.analysis.temporal_stability.compute_period_quadrants(tokens_df, evoc_quadrants_df, pos_thresholds_round_df=None, *, alpha=0.5, max_rank_value=5.0, use_users_for_frequency=True, focal_upos=None, round_digits=2, diffusion_multiplier=100.0)[source]#

Reconstruct period-specific term quadrants.

Parameters:

  • tokens_df (DataFrame)

  • evoc_quadrants_df (DataFrame)

  • pos_thresholds_round_df (DataFrame | None)

  • alpha (float)

  • max_rank_value (float)

  • use_users_for_frequency (bool)

  • focal_upos (list[str] | None)

  • round_digits (int)

  • diffusion_multiplier (float)

Return type:

DataFrame

pyevoc.analysis.temporal_stability.add_term_diffusion_summary(term_table, all_period_quadrants)[source]#

Add mean and maximum relative diffusion summaries.

Parameters:

  • term_table (DataFrame)

  • all_period_quadrants (DataFrame)

Return type:

DataFrame

pyevoc.analysis.temporal_stability.compute_stability_metrics(all_period_quadrants, n_periods)[source]#

Compute term-level and transition-level temporal stability metrics.

Parameters:

  • all_period_quadrants (DataFrame)

  • n_periods (int)

Return type:

dict[str, object]

pyevoc.analysis.temporal_stability.compute_temporal_engagement(periodised_df, *, time_col='time', doc_col='doc_id', user_col='user_id')[source]#

Compute engagement diagnostics at post/user level.

Parameters:

  • periodised_df (DataFrame)

  • time_col (str)

  • doc_col (str)

  • user_col (str)

Return type:

DataFrame

pyevoc.analysis.temporal_stability.dataframe_to_html_table(df, title, *, max_rows=100, cols=None)[source]#

Convert a dataframe to a compact HTML table section.

Parameters:

  • df (DataFrame)

  • title (str)

  • max_rows (int)

  • cols (list[str] | None)

Return type:

str

pyevoc.analysis.temporal_stability.write_temporal_report_html(results, output_file, *, max_rows=80)[source]#

Write a compact HTML report for temporal stability analysis.

Parameters:
Return type:

str

pyevoc.analysis.temporal_stability.run_temporal_stability_analysis(df, evoc_quadrants_df, pos_thresholds_round_df=None, *, n_periods=4, time_period_mode='equal_posts', custom_time_breaks=None, custom_time_cuts=None, period_labels=None, alpha=0.5, max_rank_value=5.0, use_users_for_frequency=True, focal_upos=None, round_digits=2, diffusion_multiplier=100.0, time_range_reference_df=None, count_reference_df=None, expected_min_timestamp=None, expected_max_timestamp=None, warn_on_time_range_mismatch=False, output_dir='evoc_outputs', write_html_report=True, show_tables=True, config=None)[source]#

Run the complete temporal stability analysis.

Parameters:

  • df (DataFrame)

  • evoc_quadrants_df (DataFrame)

  • pos_thresholds_round_df (DataFrame | None)

  • n_periods (int)

  • time_period_mode (str)

  • custom_time_breaks (list[str] | None)

  • custom_time_cuts (list[str] | None)

  • period_labels (list[str] | None)

  • alpha (float)

  • max_rank_value (float)

  • use_users_for_frequency (bool)

  • focal_upos (list[str] | None)

  • round_digits (int)

  • diffusion_multiplier (float)

  • time_range_reference_df (DataFrame | None)

  • count_reference_df (DataFrame | None)

  • expected_min_timestamp (object | None)

  • expected_max_timestamp (object | None)

  • warn_on_time_range_mismatch (bool)

  • output_dir (str | Path)

  • write_html_report (bool)

  • show_tables (bool)

  • config (TemporalStabilityConfig | None)

Return type:

dict[str, object]

pyevoc.analysis.temporal_stability.quadrant_trajectories(period_terms, term_col='term', period_col='period', quadrant_col='quadrant')[source]#

Backward-compatible utility returning quadrant trajectories.

Parameters:

  • period_terms (DataFrame)

  • term_col (str)

  • period_col (str)

  • quadrant_col (str)

Return type:

DataFrame

On this page
Show Source