Transcription Factor API¶

Import the transcription factor module:

from intratalkerpy import tf

The transcription factor package is split into concrete submodules:

Analysis¶

intratalkerpy.tf.IntraTalker_analysis.IntraTalker_analysis(anndataobject, tf_activities=None, arguments_list=None)¶

Description:¶

Main function that runs the IntraTalker Analysis Performs intracellular network anaysis based on conditions and clusters using decoupleR TF activity results and scRNA-seq data.

Parameters:¶

anndataobjectAnnData: Input Anndata Object as h5ad file.
tf_activitiescsv | pandas.DataFrame: Matrix with TF activities for each cell in the scRNA-seq data; Input as either csv or DataFrame.
arguments_listlist: Named list with custom options for the analysis. See validate_input_arguments in utils for further clarification.

Returns:¶

tfTFObj

Object containing tf_activities_condition,: tf_activities_cluster, average_gene_expression, regulon, CTR_input_condition, CTR_input_cluster, intracellular_network_condition, intracellular_network_cluster.

Significant TFs¶

intratalkerpy.tf.get_significant_TFs.get_significant_tfs(tf_activities_sub, condition, out_path, tf_condition_significant, celltype, pval, meanchange, plot=True, condition_comparison=False)¶

Description:¶

Analysis transcription factor activities for significant transcription factors.

Parameters:¶

tf_activities_subAnnData: Input Anndata Object with TF activities as X matrix.
conditionstr: Experiment condition (e.g. disease, knockout …).
out_pathstr: Output path to save results.
tf_condition_significantpandas.DataFrame: Condition comparison results.
celltypestr: Variable that accesses celltype meta data in anndata object.
pvalfloat: P-value to filter results.
meanchangefloat: Meanchange value to filter results.
plotbool: Boolean variable to decide if code plots heatmaps or not.
condition_comparisonbool: Comparision between multiple conditions or single condition.

Returns:¶

resdict[str, pandas.DataFrame]: A data frame with transcription factor activity scores per cell type.

Utilities¶

intratalkerpy.tf.utils.AverageExpression(sub_object, name_iterable=None, celltype=None, outpath=None)¶

Description:¶

Calculates the average gene expression of each gene per cell type for each condition.

Parameters:¶

sub_objectAnnData: AnnData object subset to one condition.
name_iterablestr: formatted name of the condition.
celltypestr: Celltype annotation.
outpathstr: Output path to save results.

Returns:¶

avg_dfpandas.DataFrame: Average gene expression of each gene per cell type.

intratalkerpy.tf.utils.add_entry(source, target, gene_A, gene_B, type_gene_A, type_gene_B, MeanLR)¶

Description:¶

Adds entry to a dataframe in the CrossTalkeR input format.

Parameters:¶

sourcepandas.Series: source cell type
targetpandas.Series: target cell type

gene_A : pandas.Series

gene_B : pandas.Series

type_gene_A : pandas.Series

type_gene_B : pandas.Series

MeanLRpandas.Series: Is the same as tf score/t value.

Returns:¶

dfdict[str, pandas.Series]: Entry in CrossTalkeR input dataframe.

intratalkerpy.tf.utils.add_node_type(df)¶

Description:¶

Adds gene type to the name of the gene.

Parameters:¶

dfpandas.DataFrame: Dataframe with all interactions.

Returns:¶

dfpandas.DataFrame: Dataframe with node type added to gene type.

intratalkerpy.tf.utils.combine_LR_and_TF(tf_table, LR_prediction, out_path, condition, add_nodetype=False)¶

Description:¶

Combining Ligand-Receptor interaction prediction with Transcription Factor interaction predictions

Parameters:¶

tf_tablepandas.DataFrame: Table with TF interactions.
LR_predictionpandas.DataFrame: Path to or dataframe with ligand-receptor interaction prediction.
out_path: str: Output path to save results.
condition: str: Sample condition of data. Used for the filename, so preferably replace special symbols with an underscore.

Returns:¶

complete_interactionspandas.DataFrame: Dataframe of with source, target, gene_A, gene_B, type_gene_A, type_gene_B, MeanLR columns for CrossTalkeR input.

intratalkerpy.tf.utils.combine_LR_and_TF_complexes(tf_table, LR_prediction, out_path, condition, add_nodetype=False)¶

Description:¶

Combining Ligand-Receptor interaction prediction with Transcription Factor interaction predictions

Parameters:¶

tf_tablepandas.DataFrame: Table with TF interactions.
LR_prediction: pandas.DataFrame: Path to or dataframe with ligand-receptor interaction prediction.
out_path: str: Output path to save results.
condition: str: Sample condition of data. Used for the filename, so preferably replace special symbols with an underscore.

Returns:¶

complete_interactionspandas.DataFrame: Dataframe of with source, target, gene_A, gene_B, type_gene_A, type_gene_B, MeanLR columns for CrossTalkeR input.

intratalkerpy.tf.utils.create_unfiltered_tf_scores(tf_scores_df, condition, celltype, out_path)¶

Description:¶

Creates a csv containing the summarized unfiltered tf scores from the decoupler TF activity dataframe.

Parameters:¶

tf_scores_dfpandas.DataFrame: Dataframe with TF activity scores.
conditionstr: Condition annotation.
celltypestr: Celltype anntotation.
out_pathstr: Output path to save results.

Returns:¶

summarized_tf_scores_dfpandas.DataFrame: Dataframe with TF score per celltype for all TFs.

intratalkerpy.tf.utils.eval_meanchange_tag(meanchange)¶

Description:¶

Creates significance tags based on the meanchange.

Parameters:¶

meanchange: float: Meanchange to be evaluated.

Returns:¶

txtstr: Significance tags for TF scores based on their meanchange.

intratalkerpy.tf.utils.eval_pval(p_val)¶

Description:¶

Creates significance tags based on the p-value.

Parameters:¶

p_valfloat: P-value to be evaluated.

Returns:¶

txtstr: Significance tags for TF scores based on their p-value.

intratalkerpy.tf.utils.load_csv(filename)¶

Description:¶

Loads a CSV file from the package’s data folder.

Parameters:¶

filenamestr: Path to the file.

Returns:¶

fcsv: Loaded CSV.

intratalkerpy.tf.utils.load_tf_activities(anndataobject, tf_activities, arguments_list)¶: Load TF activity values from an explicit input or fall back to anndataobject.obsm[‘score_ulm’] when available.

intratalkerpy.tf.utils.map_t_value(tf_scores_df, anndataobject_markers)¶

Description:¶

Merges the significant gene output from the dc.tl.rankby_group function with the t value/tf score from the filtered and summarized decoupler tf activity dataframe.

Parameters:¶

tf_scores_df : pandas.DataFrame

anndataobject_markers : pandas.DataFrame

Returns:¶

t_value_dfpandas.DataFrame: Dataframe with gene, cell type, significance tag and t-value.

intratalkerpy.tf.utils.save_variable_tf_score(filtered_summarized_tf_scores_df, condition, out_path, plot)¶

Description:¶

This function saves the transcription factor activity scores per cell type into a csv table.

Parameters:¶

filtered_summarized_tf_scores_dfpandas.DataFrame: Data frame with transcription factor activity scores per cell type.
conditionstr: Sample condition for file naming(e.g. control, disease …)
out_pathstr: Output path to save results.

Returns:¶

filtered_summarized_tf_scores_df_varpandas.DataFrame: Dataframe with TF scores and their variance over cell types for filtered genes.

intratalkerpy.tf.utils.validate_input_arguments(arguments_list)¶

Description: ————-() Checks arguments passed by User for validity.

Parameters:¶

arguments_list : list(str, float, bool)

List of user defined arguments. They include:

out_pathstr: Output path to save results.
celltypestr: Metadata field containing cell type annotations.
conditionstr: Metadata field containing condition annotations.
organismstr: “human” or “mouse”.
meanchangefloat: Cutoff value for meanchange.
pvalfloat: Cutoff value for p-value.
num_cell_filterint: Minimum number of cells in each cell type.
regstr | pandas.DataFrame: Path to regulon csv or direct input as pandas.DataFrame. Must include source, target and weight columns.
plotbool: Whether to generate plots or not.
decoupler_matrix_formatstr: “R” or “Python”, since csvs generated by the R version of decoupler need to be transposed.

Returns:¶

arguments_listlist: Validated list of arguments.

TF Object¶

intratalkerpy.tf.tfobject.make_TFOBj(tf_activities_condition: list, tf_activities_cluster: list, average_gene_expression: list, regulon: DataFrame, CTR_input_condition: list, CTR_input_cluster: list, intracellular_network_condition: list, intracellular_network_cluster: list)¶

Description:¶

Saves the IntraTalker Analysis results in an object.

Parameters:¶

tf_activities_conditionlist: List of tf activities dataframes from compared condition analysis per condition.
tf_activities_clusterlist: List of tf activities dataframes from cluster analysis per condition.
average_gene_expressionlist: List of average gene expression dataframes per condition.
regulonDataFrame: Regulon with source and target genes.
CTR_input_conditionlist: List of CrossTalkeR input dataframes from compared condition analysis per condition.
CTR_input_clusterlist: List of CrossTalkeR input dataframes from cluster analysis per condition.
intracellular_network_conditionlist: List of intracellular network dataframes from compared condition analysis per condition.
intracellular_network_clusterlist: List of intracellular network dataframes from cluster analysis per condition.

Returns:¶

tfTFObj: Object with IntraTalker Analysis results.

Condition Significance¶

intratalkerpy.tf.get_condition_significant.condition_comparison_significant(tf_activities, out_path, celltype, condition, comparison_list, num_cell_filter=0)¶

Description:¶

Creates a dataframe with all significant TFs for a pairwise comparison of two conditions given in the condition list.

Parameters:¶

tf_activitiesAnnData: TF activities anndata object.
out_pathstr: Output path to save results.
comparison_listlist: List of wished comparisons.
num_cell_filterint: Minimum number of cells in each cell type.

Returns:¶

vs_df_dicdict[str, pandas.DataFrame]: Dictionary with one dataframe per comparison containing all marker TFs found in condition comparison analysis with respective condition, reference, tf, scores, meanchange, pvals, pvals_adj, CellType, FDR, r and significance tag.

Network Generation¶

intratalkerpy.tf.generate_intracellular_network.generate_CrossTalkeR_input(tf_activities, gene_expression, regulon, organism='human')¶

Description:¶

Generates CrossTalkeR input from significant tf table.

This function loads the transcription factor activity table/data frame for multiple cell types, and generates the CrossTalkeR input table. The returned input table contains receptor-transcription factor and transcription factor-ligand interactions based on the OmniPath database and the DoRothEA regulon.

Parameters:¶

tf_activitiespandas.DataFrame: Data Frame with transcription factor activities by cell type.
gene_expression :pandas. DataFrame: Table with average gene expression levels.
regulonpandas.DataFrame: Regulon with source and target genes.
organismstr: Organism for which the data is being processed.

Returns:¶

output_dfpandas.DataFrame: A data frame with CrossTalkeR input

intratalkerpy.tf.generate_intracellular_network.generate_intracellular_network(tf_activities, gene_expression, regulon, organism='human')¶

Description:¶

Generate connections in intracellular network.

This function loads the transcription factor activity table/data frame for multiple cell types, and generates a table containing all detected intracellular connections.

Parameters:¶

tf_activitiespandas.DataFrame: Data Frame with transcription factor activities by cell type.
gene_expressionpandas.DataFrame: Table with average gene expression levels.
regulonpandas.DataFrame: Regulon with source and target genes.
organismstr: Organism for which the data is being processed.

Returns:¶

recept_regulonpandas.DataFrame: A data frame with intracellular network.

Plotting¶

intratalkerpy.tf.plot.h_clust(data)¶

Description:¶

Hierarchichal clustering of TF scores.

Parameters:¶

datapandas.DataFrame: Dataframe with TF scores.

Returns:¶

linkage_matrix: Hierarchically clustered TF scores.

intratalkerpy.tf.plot.plot_condition_tf_activities(tf_activity_tables, out_path, which='both')¶

Description:¶

Generates cluster and condition heatmap with r effect size only for significant genes. Plots heatmap of significant TFs and their activity scores from the compared condition analysis.

Parameters:¶

tf_activity_tables: pandas.DataFrame: Dataframe with TF scores.
out_path: str: Output path for results.
whichstr: Which heatmaps to plot (“annotated”, “compressed” or “both”).

Returns:¶

None

intratalkerpy.tf.plot.plot_tf_activity(filtered_summarized_tf_scores_df, tag_mapping, condition, out_path, which='both')¶

Description:¶

Plots the tf activity t-values with respective genes for cluster analysis as annotated and compressed heatmaps and saves them as separate PDFs.

Parameters:¶

filtered_summarized_tf_scores_dfpandas.DataFrame: DataFrame with TF scores.
tag_mappingpandas.DataFrame: Significance tag annotation DataFrame of the same size as the tf score DataFrame.
conditionstr: Sample condition for file naming(e.g. control, disease …)
out_pathstr: Output path to save results.
whichstr: Which heatmaps to plot (“annotated”, “compressed” or “both”).

Returns:¶

None

intratalkerpy.tf.plot.plot_top_variable_tfs(filtered_summarized_tf_scores_df_var, condition, out_path)¶

Description:¶

Plots the top 20 variable TFs as a heatmap and saves it as a PDF.

Parameters:¶

filtered_summarized_tf_scores_dfpandas.DataFrame: DataFrame with TF scores.
conditionstr: Sample condition for file naming(e.g. control, disease …)
out_pathstr: Output path to save results.

Returns:¶

None