interactor_significance_results

Results and analysis for transcription factor interaction significance testing.

tfbpmodeling.interactor_significance_results

InteractorSignificanceResults 

InteractorSignificanceResults(evaluations)

Container for storing and analyzing the results of interactor significance testing.

This class holds evaluations comparing the predictive power of interaction terms versus their corresponding main effects in a model, based on cross-validated R².

Provides methods to: - Convert results to a DataFrame. - Serialize and deserialize results from disk. - Select final model terms by comparing interaction and main effect performance.

Initialize the evaluations object.

Parameters:
  • evaluations (list[dict[str, Any]]) –

    A list of dictionaries containing significance test results.
Source code in tfbpmodeling/interactor_significance_results.py 
22
23
24
25
26
27
28
29
def __init__(self, evaluations: list[dict[str, Any]]):
    """
    Initialize the evaluations object.

    :param evaluations: A list of dictionaries containing significance test results.

    """
    self.evaluations = evaluations

deserialize classmethod 

deserialize(filepath)

Load evaluations from a JSON file.

Parameters:
  • filepath (str) –

    Path to the JSON file containing evaluation results.
Returns:
Raises:
  • ValueError –

    If the JSON content is not a list.
Source code in tfbpmodeling/interactor_significance_results.py 
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
@classmethod
def deserialize(cls, filepath: str) -> "InteractorSignificanceResults":
    """
    Load evaluations from a JSON file.

    :param filepath: Path to the JSON file containing evaluation results.
    :return: An instance of `InteractorSignificanceResults`.

    :raises ValueError: If the JSON content is not a list.

    """
    with open(filepath) as f:
        evaluations = json.load(f)

    if not isinstance(evaluations, list):
        raise ValueError(
            f"Invalid JSON format: Expected a list, got {type(evaluations)}"
        )

    return cls(evaluations)

final_model 

final_model()

Select the preferred model terms based on R² comparison.

For each interactor, compares R² of the full model (with interaction term) to that of a model where the interactor is replaced by its main effect. Whichever yields higher R² is retained.

Returns:
  • list[str] –

    List of selected model terms (interactor or main effect).
Source code in tfbpmodeling/interactor_significance_results.py 
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
def final_model(self) -> list[str]:
    """
    Select the preferred model terms based on R² comparison.

    For each interactor, compares R² of the full model (with interaction term) to
    that of a model where the interactor is replaced by its main effect. Whichever
    yields higher R² is retained.

    :return: List of selected model terms (interactor or main effect).

    """
    df = self.to_dataframe()

    if df.empty:
        return []

    # Select either the interactor or the variant based on max R²
    df["selected"] = np.where(
        df["avg_r2_interactor"] >= df["avg_r2_main_effect"],
        df["interactor"],
        df["variant"],
    )

    return df["selected"].tolist()

serialize 

serialize(filepath)

Save the evaluations to a JSON file.

Parameters:
  • filepath (str) –

    Path to the output JSON file.
Source code in tfbpmodeling/interactor_significance_results.py 
40
41
42
43
44
45
46
47
48
def serialize(self, filepath: str) -> None:
    """
    Save the evaluations to a JSON file.

    :param filepath: Path to the output JSON file.

    """
    with open(filepath, "w") as f:
        json.dump(self.evaluations, f, indent=4)

to_dataframe 

to_dataframe()

Return evaluations as a Pandas DataFrame.

Returns:
  • DataFrame –

    DataFrame containing the significance test results.
Source code in tfbpmodeling/interactor_significance_results.py 
31
32
33
34
35
36
37
38
def to_dataframe(self) -> pd.DataFrame:
    """
    Return evaluations as a Pandas DataFrame.

    :return: DataFrame containing the significance test results.

    """
    return pd.DataFrame(self.evaluations)

Overview

The interactor_significance_results module provides classes for storing, analyzing, and reporting the results of interaction significance testing. This is used in Stage 4 of the tfbpmodeling workflow to evaluate whether interaction terms provide significant explanatory power beyond main effects.

Key Features

  • Interaction vs Main Effect Comparison: Statistical comparison of interaction and main effect models
  • Significance Testing: P-value calculation and hypothesis testing
  • Effect Size Analysis: Quantification of interaction effect magnitudes
  • Result Summarization: Comprehensive reporting of significant interactions

Usage Examples

Basic Usage

from tfbpmodeling.interactor_significance_results import InteractorSignificanceResults

# Create results object
results = InteractorSignificanceResults(
    interaction_effects=interaction_coefs,
    main_effects=main_coefs,
    p_values=p_vals,
    feature_names=features
)

# Get significant interactions
significant_interactions = results.get_significant_interactions(alpha=0.05)

# Export results
results.save_results('./output/')

Analysis and Reporting

# Generate summary statistics
summary = results.get_summary_statistics()

# Plot interaction effects
results.plot_interaction_effects()

# Create comparison table
comparison_table = results.create_comparison_table()