moDiNA

Submodules

modina.context_net_inference module

modina.context_net_inference.calculate_association_scores(ord_data, nom_data, cont_data, bi_data, test_type='nonparametric', num_workers=1, nan_value=-89.0, correction='bh')

Return type:

DataFrame

modina.context_net_inference.compute_context_scores(context_data, meta_file, test_type='nonparametric', correction='bh', num_workers=1, path=None, nan_value=None, name='context1')

Compute association scores for a given context.

Parameters:

• context_data (DataFrame) – Raw context data (rows: samples, columns: variables).

• meta_file (DataFrame) – Metadata file containing a ‘label’ and ‘type’ column to specify the data type of each variable.

• test_type (str) – Type of tests to use for network inference. Defaults to ‘nonparametric’.

• correction (str) – Correction method for multiple testing. Defaults to ‘bh’.

• num_workers (int) – Number of workers for parallel processing. Defaults to 1.

• path (Optional[str]) – Optional path to save the computed scores as a CSV file. Defaults to None.

• nan_value (Optional[float]) – Numerical value used for NaN values in the context data. If None, an error will be raised if such values are present. Defaults to None.

• name (str) – Name of the context. Used for saving files. Defaults to ‘context’.

Return type:

DataFrame

Returns:

A pd.DataFrame containing the computed association scores.

modina.context_net_inference.napy_bi_cont(cont_phenotypes, bi_phenotypes, test='nonparametric', num_workers=8, nan_value=-89.0)

modina.context_net_inference.napy_bi_nom(nom_phenotypes, bi_phenotypes, num_workers=8, nan_value=-89.0)

modina.context_net_inference.napy_bi_ord(ord_phenotypes, bi_phenotypes, num_workers=8, nan_value=-89.0)

modina.context_net_inference.napy_cont_cont(cont_phenotypes, test='nonparametric', num_workers=8, nan_value=-89.0)

modina.context_net_inference.napy_nom_cont(cont_phenotypes, nom_phenotypes, test='nonparametric', num_workers=8, nan_value=-89.0)

modina.context_net_inference.napy_ord_cont(cont_phenotypes, ord_phenotypes, num_workers=8, nan_value=-89.0)

modina.context_net_inference.napy_ord_nom(ord_phenotypes, nom_phenotypes, num_workers=8, nan_value=-89.0)

modina.context_simulation module

modina.context_simulation.save_gt(groundtruths, path, mode='node', edge_magnitude=None, node_stats=None)

Write ground truth nodes or edges to a two- (or, with the optional data below, wider-) column file.

Parameters:

• groundtruths – (shift_nodes, corr_nodes, shift_corr_nodes) as returned by simulate_copula.

• path – File to write.

• mode – ‘node’ writes one row per (node, description); ‘edge’ writes one row per (edge, description), edge = ‘_’.join(sorted(pair)).

• edge_magnitude – Optional, mode=’edge’ only. Dict keyed by frozenset({node1, node2}) -> the jittered correlation magnitude injected on that edge. When given, an extra jittered_magnitude column is appended. Omit to reproduce the historical two-column file exactly (used unchanged by context_simulation_advanced.save_gt_advanced).

• node_stats – Optional, mode=’node’ only. Dict node -> (n_edges_tweaked, sum_jittered_magnitude). When given, two extra columns are appended; a node absent from the dict (e.g. mean-shift-only) is written as (0, 0.0). Omit to reproduce the historical two-column file exactly.

modina.context_simulation.simulate_copula(path=None, name1='context1', name2='context2', n_bi=50, n_cont=50, n_cat=50, n_samples_1=500, n_samples_2=500, n_shift_cont=0, n_shift_bi=0, n_shift_cat=0, n_corr_cont_cont=0, n_corr_bi_bi=0, n_corr_cat_cat=0, n_corr_bi_cont=0, n_corr_bi_cat=0, n_corr_cont_cat=0, n_both_cont_cont=0, n_both_bi_bi=0, n_both_cat_cat=0, n_both_bi_cont=0, n_both_bi_cat=0, n_both_cont_cat=0, shift=0.5, corr=0.7, hub_reuse_prob=0.0, binary_p_low=0.3, binary_p_high=0.7, ordinal_concentration=20.0)

Simulate two contexts with binary and continuous nodes using a Gaussian copula.

Parameters:

• path – Path to save the simulated contexts, the meta file and the ground truth information. If None, files are not saved.

• name1 – Name of the first context.

• name2 – Name of the second context.

• n_bi – Number of binary nodes to simulate.

• n_cont – Number of continuous nodes to simulate.

• n_cat – Number of categorical nodes to simulate.

• n_samples_1 – Number of samples for the first context.

• n_samples_2 – Number of samples for the second context.

• n_shift_cont – Number of continuous nodes with an artificially introduced mean shift.

• n_shift_bi – Number of binary nodes with an artificially introduced mean shift.

• n_shift_cat – Number of categorical nodes with an artificially introduced mean shift.

• n_corr_cont_cont – Number of continuous node pairs with an artifically introduced correlation difference.

• n_corr_bi_bi – Number of binary node pairs with an artificially introduced correlation difference.

• n_corr_cat_cat – Number of categorical node pairs with an artificially introduced correlation difference.

• n_corr_bi_cat – Number of binary-categorical node pairs with an artificially introduced correlation difference.

• n_corr_cont_cat – Number of continuous-categorical node pairs with an artificially introduced correlation difference.

• n_corr_bi_cont – Number of mixed node pairs with an artificially introduced correlation difference.

• n_both_cont_cont – Number of continuous node pairs with both an aritificially introduced mean shift and correlation difference.

• n_both_bi_bi – Number of binary node pairs with both an artificially introduced mean shift and correlation difference.

• n_both_cat_cat – Number of categorical node pairs with both an artificially introduced mean shift and correlation difference.

• n_both_bi_cat – Number of binary-categorical node pairs with both an artificially introduced mean shift and correlation difference.

• n_both_cont_cat – Number of continuous-categorical node pairs with both an artificially introduced mean shift and correlation difference.

• n_both_bi_cont – Number of mixed node pairs with both an artificially introduced mean shift and correlation difference.

• shift – Target magnitude of the mean shift. Each shifted node draws its actual magnitude uniformly from [shift - 0.1, shift + 0.1] (floored at 0) so ground truth effects vary in strength rather than all being identical.

• corr – Target magnitude of the correlation difference (measured as correlation coefficient between 0 and 1). Each correlated pair draws its actual magnitude uniformly from [corr - 0.1, corr + 0.1] (clipped to [0, 0.95]) so ground truth effects vary in strength rather than all being identical.

• hub_reuse_prob – Probability that a new correlation/both pair reuses an already-placed node as one endpoint (“hub”) instead of drawing two fresh nodes. Real differential networks concentrate rewiring on a few hub nodes rather than a perfect matching. When it fires, exactly one of the pair’s two slots is filled by a node that already has at least one edge; the other slot is always a fresh node, and that fresh node – plus the hub’s original first partner, the first time the hub is reused – is permanently barred from ever being reused itself. This keeps every hub isolated from every other hub, which is what makes the one cheap check below exact: a reuse is only committed if the hub’s running sum of its edges’ magnitude**2 stays below _HUB_SUMSQ_CEILING (0.95); otherwise it is abandoned and a fresh pair is drawn instead, silently, with no shrinking or retry. Default 0.0 reproduces the historical one-edge-per-node behaviour exactly.

• binary_p_low – Lower bound of the base rate drawn per binary node. How strongly two binary variables can correlate is capped by how balanced they are, so a rare node attenuates the correlation difference actually realised on its edges. Widen this range for more marginal variety, at the cost of less comparable effect sizes across edges. Use 0.0/1.0 for the historical behaviour.

• binary_p_high – Upper bound of the base rate drawn per binary node.

• ordinal_concentration – Symmetric Dirichlet concentration for the category probabilities of each ordinal node. Large values keep the categories near-balanced; 1.0 (the historical behaviour) is uniform over all splits and routinely leaves categories nearly empty.

Returns:

A tuple containing the two simulated contexts, a meta file, a list of ground truth nodes and a dict of per-edge/per-node injected effect sizes. - context1: pd.DataFrame of the first simulated context. - context2: pd.DataFrame of the second simulated context. - meta: pd.DataFrame containing the data type for each simulated variable. - ground_truth: A tuple containing three lists of ground truth nodes: (shift_nodes, corr_nodes, shift_corr_nodes). - effects: dict with ‘edge_magnitude’ (dict keyed by frozenset({node1, node2}) -> the

jittered correlation magnitude actually injected on that edge), ‘node_degree’ (dict node -> number of correlation edges touching it) and ‘node_sum_magnitude’ (dict node -> sum of jittered magnitudes over those edges). Feeds the extra columns written to ground_truth_edges.txt/ground_truth_nodes.txt when path is given, and lets a caller that writes those files itself (as the Nextflow CLI wrapper does) do the same.

modina.diff_net_construction module

modina.diff_net_construction.compute_diff_edges(scores1, scores2, edge_metric, max_path_length=2, path=None, name1='context1', name2='context2')

Compute differential edge scores based on the specified edge metric.

Parameters:

• scores1 (DataFrame) – Statistical association scores of Context 1, rescaled and potentially filtered.

• scores2 (DataFrame) – Statistical association scores of Context 2, rescaled and potentially filtered.

• edge_metric (str) – Edge metric to compute the differential edge scores.

• max_path_length (int) – Maximum length of paths to consider in the computation of integrated interaction scores. Defaults to 2.

• path (Optional[str]) – Optional path to save the differential edge scores as a CSV file. Defaults to None.

• name1 (str) – Name of Context 1, used to label the per-context raw-P/raw-E columns. Defaults to ‘context1’.

• name2 (str) – Name of Context 2, used to label the per-context raw-P/raw-E columns. Defaults to ‘context2’.

Return type:

DataFrame | None | Series

Returns:

A tuple (edges_diff, edge_node_stats): the computed differential edge scores and a node-indexed DataFrame of per-node statistics over incident edges (see edge_node_statistics).

modina.diff_net_construction.compute_diff_network(scores1, scores2, context1, context2, edge_metric=None, node_metric=None, max_path_length=2, correction='bh', num_workers=1, path=None, format='csv', meta_file=None, test_type='nonparametric', nan_value=None, name1='context1', name2='context2')

Computation of a differential network defined by a node metric and an edge metric.

Parameters:

• scores1 (DataFrame) – Statistical association scores of Context 1, rescaled and potentially filtered.

• scores2 (DataFrame) – Statistical association scores of Context 2, rescaled and potentially filtered.

• context1 (DataFrame) – Observed data of Context 1, potentially filtered.

• context2 (DataFrame) – Observed data of Context 2, potentially filtered.

• edge_metric (Optional[str]) – Edge metric used to construct the differential network.

• node_metric (Optional[str]) – Node metric used to construct the differential network.

• max_path_length (int) – Maximum length of paths to consider in the computation of integrated interaction scores. Defaults to 2.

• correction (str) – Correction method for multiple testing. Defaults to ‘bh’.

• num_workers (int) – Number of workers for parallel computation of STC. Defaults to 1.

• path (Optional[str]) – Optional path to save the differential scores as CSV files. Defaults to None.

• format (str) – File format to save the differential network. Options are ‘csv’ and ‘graphml’. Defaults to ‘csv’.

• meta_file (Optional[DataFrame]) – Meta file containing the node types. Only needed if node_metric is ‘STC’. Defaults to None.

• test_type (str) – Test type to use for continuous nodes in STC metric. Defaults to ‘nonparametric’.

• nan_value (Optional[int]) – Numerical value used for NaN values in the context data. If None, an error will be raised if such values are present. Defaults to None.

Return type:

Tuple[Series | DataFrame | None, Series | DataFrame | None]

Returns:

A tuple (edges_diff, nodes_diff, edge_node_stats) containing the computed differential edges, differential nodes, and per-node statistics over incident edges (None if no edge_metric).

modina.diff_net_construction.compute_diff_nodes(scores1, scores2, context1, context2, node_metric, correction='bh', meta_file=None, test_type='nonparametric', nan_value=None, num_workers=1, path=None)

Compute differential node scores based on the specified node metric.

Parameters:

• scores1 (DataFrame) – Statistical association scores of Context 1, rescaled and potentially filtered.

• scores2 (DataFrame) – Statistical association scores of Context 2, rescaled and potentially filtered.

• context1 (DataFrame) – Observed data of Context 1, potentially filtered.

• context2 (DataFrame) – Observed data of Context 2, potentially filtered.

• node_metric (str) – Node metric to compute the differential node scores.

• correction (str) – Correction method for multiple testing. Only needed if node_metric is ‘STC’. Defaults to ‘bh’.

• meta_file (Optional[DataFrame]) – Meta file containing the node types. Only needed if node_metric is ‘STC’. Defaults to None.

• test_type (str) – Test type to compare continuous variables across contexts for the ‘STC’ node metric. Defaults to ‘nonparametric’.

• nan_value (Optional[int]) – Numerical value used for NaN values in the context data. If None, an error will be raised if such values are present. Defaults to None.

• num_workers (int) – Number of workers for parallel computation of STC. Only needed if node_metric is ‘STC’. Defaults to 1.

• path (Optional[str]) – Optional path to save the differential node scores as a CSV file. Defaults to None.

Return type:

DataFrame | None | Series

Returns:

A DataFrame containing the computed differential node scores.

modina.diff_net_construction.degree_centrality(nodes_diff, scores1, scores2, metric='DC-P')

modina.diff_net_construction.edge_node_statistics(edges_diff, edge_metric)

Compute summary statistics of the (absolute) edge metric over the edges incident to each node.

Parameters:

• edges_diff (DataFrame) – Differential edge scores with columns ‘label1’, ‘label2’ and edge_metric.

• edge_metric (str) – Name of the (absolute) edge metric column.

Return type:

DataFrame

Returns:

A node-indexed DataFrame with columns ‘edge-min’, ‘edge-max’, ‘edge-median’, ‘edge-mean’, ‘edge-sd’ and ‘edge-percentile-mean’. sd is the sample standard deviation (ddof=1) and is NaN for nodes with a single incident edge. ‘edge-percentile-mean’ is the mean, over a node’s incident edges, of each edge’s percentile rank within the global distribution of all edges (in (0, 1]); it captures how high a node’s edges sit relative to all edges in the network.

modina.diff_net_construction.interaction_score(data, max_path_length=3, metric='rescaled-E')

modina.diff_net_construction.pagerank_centrality(nodes_diff, scores1, scores2, metric='PRC-P')

modina.diff_net_construction.stat_test_centrality(context1, context2, meta_file, test_type='nonparametric', correction='bh', nan_value=None, num_workers=1)

modina.edge_filtering module

modina.edge_filtering.filter(scores1, scores2, context1, context2, filter_method=None, filter_param=0.0, filter_metric=None, filter_rule=None, path=None)

Filter association scores and context data based on the specified filtering configurations.

Parameters:

• scores1 (DataFrame) – Statistical association scores of Context 1.

• scores2 (DataFrame) – Statistical association scores of Context 2.

• context1 (DataFrame) – The first context for the differential network analysis.

• context2 (DataFrame) – The second context for the differential network analysis.

• filter_method (Optional[str]) – Method used for filtering. Defaults to None.

• filter_param (float) – Parameter for the specified filtering method. Defaults to 0.0.

• filter_metric (Optional[str]) – Edge metric used for filtering. Options include ‘raw-P’ and ‘rescaled-E’. Defaults to None.

• filter_rule (Optional[str]) – Rule to integrate the networks during filtering. Defaults to None.

• path (Optional[str]) – Optional path to save the filtered scores and context data as CSV files. Defaults to None.

Return type:

Tuple[DataFrame, DataFrame, DataFrame, DataFrame]

Returns:

A tuple containing the filtered scores and context data.

modina.edge_filtering.filter_differential(edges_diff, edge_metric, filter_method=None, filter_param=0.0, path=None)

Filter the differential network by retaining the strongest edges according to the already-computed edge metric. Because the differential network is a single graph, there is no per-context integration (‘filter_rule’) and no p-value-vs-effect-size choice (‘filter_metric’): filtering always operates on the provided edge_metric.

Parameters:

• edges_diff (DataFrame) – Differential edge scores with columns ‘label1’, ‘label2’, ‘test_type’, edge_metric and edge_metric + ‘_signed’.

• edge_metric (str) – Name of the (absolute) differential edge-metric column to filter on.

• filter_method (Optional[str]) – Method used for filtering (‘degree’ or ‘density’). Defaults to None.

• filter_param (float) – Parameter for the specified filtering method. Defaults to 0.0.

• path (Optional[str]) – Optional path to save the filtered edges and per-node statistics as CSV files. Defaults to None.

Return type:

Tuple[DataFrame, DataFrame]

Returns:

A tuple (edges_filtered, edge_node_stats) with the filtered differential edges and the per-node statistics recomputed over the retained edges.

modina.edge_filtering.filter_single(scores, context, filter_method=None, filter_param=0.0, filter_metric=None, path=None)

Filter the association scores and context data of a single context network based on the specified filtering configurations. Unlike filter(), this operates on one network only and therefore does not take a ‘filter_rule’ (there is nothing to integrate across contexts).

Parameters:

• scores (DataFrame) – Statistical association scores of the context.

• context (DataFrame) – Observed data of the context (rows: samples, columns: variables).

• filter_method (Optional[str]) – Method used for filtering (‘degree’ or ‘density’). Defaults to None.

• filter_param (float) – Parameter for the specified filtering method. Defaults to 0.0.

• filter_metric (Optional[str]) – Edge metric used for filtering. Options are ‘raw-P’ and ‘rescaled-E’. Defaults to None.

• path (Optional[str]) – Optional path to save the filtered scores and context data as CSV files. Defaults to None.

Return type:

Tuple[DataFrame, DataFrame]

Returns:

A tuple (scores_filtered, context_filtered) with the filtered scores and context data.

modina.pipeline module

modina.pipeline.diffnet_analysis(context1, context2, meta_file, edge_metric=None, node_metric=None, ranking_alg='PageRank+', filter_method=None, filter_param=0.0, filter_metric=None, filter_rule=None, filter_target=None, max_path_length=2, test_type='nonparametric', nan_value=None, correction='bh', num_workers=1, project_path=None, name1='context1', name2='context2')

Wrapper function to perform an end-to-end differential network analysis following the moDiNA pipeline.

Parameters:

• context1 (DataFrame) – Observed data of Context 1 (rows: samples, columns: variables).

• context2 (DataFrame) – Observed data of Context 2 (rows: samples, columns: variables).

• meta_file (DataFrame) – Metadata file containing a ‘label’ and ‘type’ column to specify the data type of each variable.

• test_type (str) – Type of statistical tests to use for association score calculation. Defaults to ‘nonparametric’.

• nan_value (Optional[int]) – Numerical value used for NaN values in the context data. If None, an error will be raised if such values are present. Defaults to None.

• correction (str) – Correction method for multiple testing. Defaults to ‘bh’.

• num_workers (int) – Number of workers for parallel processing. Defaults to 1.

• filter_method (Optional[str]) – Method used for filtering. Defaults to None.

• filter_param (float) – Parameter for the specified filtering method. Defaults to 0.0.

• filter_metric (Optional[str]) – Edge metric used for filtering. Only used when filter_target is ‘context-specific’. Defaults to None.

• filter_rule (Optional[str]) – Rule to integrate the networks during filtering. Only used when filter_target is ‘context-specific’. Defaults to None.

• filter_target (Optional[str]) – Which network to filter. None (default) performs no filtering. ‘context-specific’ filters the two context networks before building the differential network (using filter_metric and filter_rule); ‘differential’ filters the differential network on the computed edge_metric (filter_metric and filter_rule are ignored). When filter_target is not None, filter_method must be provided.

• edge_metric (Optional[str]) – Edge metric used to construct the differential network.

• node_metric (Optional[str]) – Node metric used to construct the differential network.

• max_path_length (int) – Maximum length of paths to consider in the computation of integrated interaction scores. Defaults to 2.

• ranking_alg (str) – Ranking algorithm to compute. Options are ‘PageRank+’, ‘PageRank’, ‘absDimontRank’, ‘DimontRank’ and ‘nodeRank’. Defaults to ‘PageRank+’.

• name1 (str) – Name of Context 1. Used for saving files. Defaults to ‘context1’.

• name2 (str) – Name of Context 2. Used for saving files. Defaults to ‘context2’.

• project_path (Optional[str]) – Optional path to save results. Defaults to None.

Returns:

A tuple (ranking, edges_diff, nodes_diff, config) containing the computed ranking, differential edges, differential nodes, and configuration parameters.

modina.ranking module

modina.ranking.compute_ranking(nodes_diff, edges_diff, ranking_alg, path=None, meta_file=None, edge_node_stats=None)

Compute a ranking based on the specified ranking algorithm.

For the node-indexed rankings (‘PageRank+’, ‘PageRank’, ‘absDimontRank’, ‘DimontRank’, ‘nodeRank’) the output is additionally enriched with the node-metric value (when a node metric was employed) and with per-node statistics over the incident edges (when an edge metric was employed).

Parameters:

• nodes_diff (Union[DataFrame, Series, None]) – Differential node scores.

• edges_diff (Union[DataFrame, Series, None]) – Differential edge scores.

• ranking_alg (str) – Ranking algorithm to compute. Options are ‘PageRank+’, ‘PageRank’, ‘absDimontRank’, ‘DimontRank’ and ‘nodeRank’.

• meta_file (Optional[DataFrame]) – Metadata file containing a ‘label’ and ‘type’ column to specify the data type of each variable.

• path (Optional[str]) – Optional path to save the ranking as a CSV file.

• edge_node_stats (Optional[DataFrame]) – Optional precomputed per-node edge statistics (see edge_node_statistics). If not provided but an edge metric was employed, the statistics are computed on the fly.

Return type:

DataFrame | Series

Returns:

A DataFrame containing the ranking, enriched with the node-metric value and per-node edge statistics.

modina.ranking.dimontrank(edges_diff, edge_metric, mode='abs')

modina.ranking.pagerank(edges_diff, edge_metric, nodes_diff=None, node_metric=None, personalization=True)

modina.statistics_utils module

modina.statistics_utils.add_pval_transforms(scores)

modina.statistics_utils.cohens_d_to_r(scores1, scores2, n1, n2)

modina.statistics_utils.effect_size_to_r2(scores1, scores2, metric='transformed-E')

modina.statistics_utils.fdr_correction(pvalues, method='bh')

modina.statistics_utils.find_flagged_variables(scores1, scores2)

Return the sorted list of variables that appear as an edge endpoint in only one of scores1/scores2 – i.e. variables flagged (single observed category, or entirely missing) in exactly one context and therefore absent from that context’s association scores.

Parameters:

• scores1 (DataFrame) – Association scores of Context 1.

• scores2 (DataFrame) – Association scores of Context 2.

Return type:

list

Returns:

Sorted list of flagged variable names.

modina.statistics_utils.probit_rescaling(scores1, scores2, metric='rescaled-E')

modina.statistics_utils.reconcile_flagged_variables(scores1, scores2, context1=None, context2=None, path=None)

Align two context-specific networks onto their common set of edges, so scores1 and scores2 stay row-aligned, and report which variables ended up with no edges left in either context.

Parameters:

• scores1 (DataFrame) – Association scores of Context 1.

• scores2 (DataFrame) – Association scores of Context 2.

• context1 (Optional[DataFrame]) – Optional observed data of Context 1; if given, variables with no edges left are also dropped as columns.

• context2 (Optional[DataFrame]) – Optional observed data of Context 2; if given, variables with no edges left are also dropped as columns.

• path (Optional[str]) – Optional path to save the list of removed variables as a CSV file. Defaults to None.

Return type:

Tuple[DataFrame, DataFrame, Optional[DataFrame], Optional[DataFrame], list]

Returns:

A tuple (scores1, scores2, context1, context2, removed_variables), with scores1/scores2 restricted to their common edges (row-aligned) and context1/context2 returned unchanged (None) if not provided. ‘removed_variables’ is the sorted list of variables that no longer appear as an edge endpoint in either context (empty if none) – callers should attach it as .attrs[‘removed_variables’] on whatever they return, so it stays discoverable to a caller even when no ‘path’ is given to write it to disk (e.g. a direct Python/API call that never passes through a Nextflow bin script).

Module contents

modina.add_pval_transforms(scores)

modina.cohens_d_to_r(scores1, scores2, n1, n2)

modina.compute_context_scores(context_data, meta_file, test_type='nonparametric', correction='bh', num_workers=1, path=None, nan_value=None, name='context1')

Compute association scores for a given context.

Parameters:

• context_data (DataFrame) – Raw context data (rows: samples, columns: variables).

• meta_file (DataFrame) – Metadata file containing a ‘label’ and ‘type’ column to specify the data type of each variable.

• test_type (str) – Type of tests to use for network inference. Defaults to ‘nonparametric’.

• correction (str) – Correction method for multiple testing. Defaults to ‘bh’.

• num_workers (int) – Number of workers for parallel processing. Defaults to 1.

• path (Optional[str]) – Optional path to save the computed scores as a CSV file. Defaults to None.

• nan_value (Optional[float]) – Numerical value used for NaN values in the context data. If None, an error will be raised if such values are present. Defaults to None.

• name (str) – Name of the context. Used for saving files. Defaults to ‘context’.

Return type:

DataFrame

Returns:

A pd.DataFrame containing the computed association scores.

modina.compute_diff_edges(scores1, scores2, edge_metric, max_path_length=2, path=None, name1='context1', name2='context2')

Compute differential edge scores based on the specified edge metric.

Parameters:

• scores1 (DataFrame) – Statistical association scores of Context 1, rescaled and potentially filtered.

• scores2 (DataFrame) – Statistical association scores of Context 2, rescaled and potentially filtered.

• edge_metric (str) – Edge metric to compute the differential edge scores.

• max_path_length (int) – Maximum length of paths to consider in the computation of integrated interaction scores. Defaults to 2.

• path (Optional[str]) – Optional path to save the differential edge scores as a CSV file. Defaults to None.

• name1 (str) – Name of Context 1, used to label the per-context raw-P/raw-E columns. Defaults to ‘context1’.

• name2 (str) – Name of Context 2, used to label the per-context raw-P/raw-E columns. Defaults to ‘context2’.

Return type:

DataFrame | None | Series

Returns:

A tuple (edges_diff, edge_node_stats): the computed differential edge scores and a node-indexed DataFrame of per-node statistics over incident edges (see edge_node_statistics).

modina.compute_diff_network(scores1, scores2, context1, context2, edge_metric=None, node_metric=None, max_path_length=2, correction='bh', num_workers=1, path=None, format='csv', meta_file=None, test_type='nonparametric', nan_value=None, name1='context1', name2='context2')

Computation of a differential network defined by a node metric and an edge metric.

Parameters:

• scores1 (DataFrame) – Statistical association scores of Context 1, rescaled and potentially filtered.

• scores2 (DataFrame) – Statistical association scores of Context 2, rescaled and potentially filtered.

• context1 (DataFrame) – Observed data of Context 1, potentially filtered.

• context2 (DataFrame) – Observed data of Context 2, potentially filtered.

• edge_metric (Optional[str]) – Edge metric used to construct the differential network.

• node_metric (Optional[str]) – Node metric used to construct the differential network.

• max_path_length (int) – Maximum length of paths to consider in the computation of integrated interaction scores. Defaults to 2.

• correction (str) – Correction method for multiple testing. Defaults to ‘bh’.

• num_workers (int) – Number of workers for parallel computation of STC. Defaults to 1.

• path (Optional[str]) – Optional path to save the differential scores as CSV files. Defaults to None.

• format (str) – File format to save the differential network. Options are ‘csv’ and ‘graphml’. Defaults to ‘csv’.

• meta_file (Optional[DataFrame]) – Meta file containing the node types. Only needed if node_metric is ‘STC’. Defaults to None.

• test_type (str) – Test type to use for continuous nodes in STC metric. Defaults to ‘nonparametric’.

• nan_value (Optional[int]) – Numerical value used for NaN values in the context data. If None, an error will be raised if such values are present. Defaults to None.

Return type:

Tuple[Series | DataFrame | None, Series | DataFrame | None]

Returns:

A tuple (edges_diff, nodes_diff, edge_node_stats) containing the computed differential edges, differential nodes, and per-node statistics over incident edges (None if no edge_metric).

modina.compute_diff_nodes(scores1, scores2, context1, context2, node_metric, correction='bh', meta_file=None, test_type='nonparametric', nan_value=None, num_workers=1, path=None)

Compute differential node scores based on the specified node metric.

Parameters:

• scores1 (DataFrame) – Statistical association scores of Context 1, rescaled and potentially filtered.

• scores2 (DataFrame) – Statistical association scores of Context 2, rescaled and potentially filtered.

• context1 (DataFrame) – Observed data of Context 1, potentially filtered.

• context2 (DataFrame) – Observed data of Context 2, potentially filtered.

• node_metric (str) – Node metric to compute the differential node scores.

• correction (str) – Correction method for multiple testing. Only needed if node_metric is ‘STC’. Defaults to ‘bh’.

• meta_file (Optional[DataFrame]) – Meta file containing the node types. Only needed if node_metric is ‘STC’. Defaults to None.

• test_type (str) – Test type to compare continuous variables across contexts for the ‘STC’ node metric. Defaults to ‘nonparametric’.

• nan_value (Optional[int]) – Numerical value used for NaN values in the context data. If None, an error will be raised if such values are present. Defaults to None.

• num_workers (int) – Number of workers for parallel computation of STC. Only needed if node_metric is ‘STC’. Defaults to 1.

• path (Optional[str]) – Optional path to save the differential node scores as a CSV file. Defaults to None.

Return type:

DataFrame | None | Series

Returns:

A DataFrame containing the computed differential node scores.

modina.compute_ranking(nodes_diff, edges_diff, ranking_alg, path=None, meta_file=None, edge_node_stats=None)

Compute a ranking based on the specified ranking algorithm.

For the node-indexed rankings (‘PageRank+’, ‘PageRank’, ‘absDimontRank’, ‘DimontRank’, ‘nodeRank’) the output is additionally enriched with the node-metric value (when a node metric was employed) and with per-node statistics over the incident edges (when an edge metric was employed).

Parameters:

• nodes_diff (Union[DataFrame, Series, None]) – Differential node scores.

• edges_diff (Union[DataFrame, Series, None]) – Differential edge scores.

• ranking_alg (str) – Ranking algorithm to compute. Options are ‘PageRank+’, ‘PageRank’, ‘absDimontRank’, ‘DimontRank’ and ‘nodeRank’.

• meta_file (Optional[DataFrame]) – Metadata file containing a ‘label’ and ‘type’ column to specify the data type of each variable.

• path (Optional[str]) – Optional path to save the ranking as a CSV file.

• edge_node_stats (Optional[DataFrame]) – Optional precomputed per-node edge statistics (see edge_node_statistics). If not provided but an edge metric was employed, the statistics are computed on the fly.

Return type:

DataFrame | Series

Returns:

A DataFrame containing the ranking, enriched with the node-metric value and per-node edge statistics.

modina.diffnet_analysis(context1, context2, meta_file, edge_metric=None, node_metric=None, ranking_alg='PageRank+', filter_method=None, filter_param=0.0, filter_metric=None, filter_rule=None, filter_target=None, max_path_length=2, test_type='nonparametric', nan_value=None, correction='bh', num_workers=1, project_path=None, name1='context1', name2='context2')

Wrapper function to perform an end-to-end differential network analysis following the moDiNA pipeline.

Parameters:

• context1 (DataFrame) – Observed data of Context 1 (rows: samples, columns: variables).

• context2 (DataFrame) – Observed data of Context 2 (rows: samples, columns: variables).

• meta_file (DataFrame) – Metadata file containing a ‘label’ and ‘type’ column to specify the data type of each variable.

• test_type (str) – Type of statistical tests to use for association score calculation. Defaults to ‘nonparametric’.

• nan_value (Optional[int]) – Numerical value used for NaN values in the context data. If None, an error will be raised if such values are present. Defaults to None.

• correction (str) – Correction method for multiple testing. Defaults to ‘bh’.

• num_workers (int) – Number of workers for parallel processing. Defaults to 1.

• filter_method (Optional[str]) – Method used for filtering. Defaults to None.

• filter_param (float) – Parameter for the specified filtering method. Defaults to 0.0.

• filter_metric (Optional[str]) – Edge metric used for filtering. Only used when filter_target is ‘context-specific’. Defaults to None.

• filter_rule (Optional[str]) – Rule to integrate the networks during filtering. Only used when filter_target is ‘context-specific’. Defaults to None.

• filter_target (Optional[str]) – Which network to filter. None (default) performs no filtering. ‘context-specific’ filters the two context networks before building the differential network (using filter_metric and filter_rule); ‘differential’ filters the differential network on the computed edge_metric (filter_metric and filter_rule are ignored). When filter_target is not None, filter_method must be provided.

• edge_metric (Optional[str]) – Edge metric used to construct the differential network.

• node_metric (Optional[str]) – Node metric used to construct the differential network.

• max_path_length (int) – Maximum length of paths to consider in the computation of integrated interaction scores. Defaults to 2.

• ranking_alg (str) – Ranking algorithm to compute. Options are ‘PageRank+’, ‘PageRank’, ‘absDimontRank’, ‘DimontRank’ and ‘nodeRank’. Defaults to ‘PageRank+’.

• name1 (str) – Name of Context 1. Used for saving files. Defaults to ‘context1’.

• name2 (str) – Name of Context 2. Used for saving files. Defaults to ‘context2’.

• project_path (Optional[str]) – Optional path to save results. Defaults to None.

Returns:

A tuple (ranking, edges_diff, nodes_diff, config) containing the computed ranking, differential edges, differential nodes, and configuration parameters.

modina.edge_node_statistics(edges_diff, edge_metric)

Compute summary statistics of the (absolute) edge metric over the edges incident to each node.

Parameters:

• edges_diff (DataFrame) – Differential edge scores with columns ‘label1’, ‘label2’ and edge_metric.

• edge_metric (str) – Name of the (absolute) edge metric column.

Return type:

DataFrame

Returns:

A node-indexed DataFrame with columns ‘edge-min’, ‘edge-max’, ‘edge-median’, ‘edge-mean’, ‘edge-sd’ and ‘edge-percentile-mean’. sd is the sample standard deviation (ddof=1) and is NaN for nodes with a single incident edge. ‘edge-percentile-mean’ is the mean, over a node’s incident edges, of each edge’s percentile rank within the global distribution of all edges (in (0, 1]); it captures how high a node’s edges sit relative to all edges in the network.

modina.effect_size_to_r2(scores1, scores2, metric='transformed-E')

modina.filter(scores1, scores2, context1, context2, filter_method=None, filter_param=0.0, filter_metric=None, filter_rule=None, path=None)

Filter association scores and context data based on the specified filtering configurations.

Parameters:

• scores1 (DataFrame) – Statistical association scores of Context 1.

• scores2 (DataFrame) – Statistical association scores of Context 2.

• context1 (DataFrame) – The first context for the differential network analysis.

• context2 (DataFrame) – The second context for the differential network analysis.

• filter_method (Optional[str]) – Method used for filtering. Defaults to None.

• filter_param (float) – Parameter for the specified filtering method. Defaults to 0.0.

• filter_metric (Optional[str]) – Edge metric used for filtering. Options include ‘raw-P’ and ‘rescaled-E’. Defaults to None.

• filter_rule (Optional[str]) – Rule to integrate the networks during filtering. Defaults to None.

• path (Optional[str]) – Optional path to save the filtered scores and context data as CSV files. Defaults to None.

Return type:

Tuple[DataFrame, DataFrame, DataFrame, DataFrame]

Returns:

A tuple containing the filtered scores and context data.

modina.filter_differential(edges_diff, edge_metric, filter_method=None, filter_param=0.0, path=None)

Filter the differential network by retaining the strongest edges according to the already-computed edge metric. Because the differential network is a single graph, there is no per-context integration (‘filter_rule’) and no p-value-vs-effect-size choice (‘filter_metric’): filtering always operates on the provided edge_metric.

Parameters:

• edges_diff (DataFrame) – Differential edge scores with columns ‘label1’, ‘label2’, ‘test_type’, edge_metric and edge_metric + ‘_signed’.

• edge_metric (str) – Name of the (absolute) differential edge-metric column to filter on.

• filter_method (Optional[str]) – Method used for filtering (‘degree’ or ‘density’). Defaults to None.

• filter_param (float) – Parameter for the specified filtering method. Defaults to 0.0.

• path (Optional[str]) – Optional path to save the filtered edges and per-node statistics as CSV files. Defaults to None.

Return type:

Tuple[DataFrame, DataFrame]

Returns:

A tuple (edges_filtered, edge_node_stats) with the filtered differential edges and the per-node statistics recomputed over the retained edges.

modina.filter_single(scores, context, filter_method=None, filter_param=0.0, filter_metric=None, path=None)

Filter the association scores and context data of a single context network based on the specified filtering configurations. Unlike filter(), this operates on one network only and therefore does not take a ‘filter_rule’ (there is nothing to integrate across contexts).

Parameters:

• scores (DataFrame) – Statistical association scores of the context.

• context (DataFrame) – Observed data of the context (rows: samples, columns: variables).

• filter_method (Optional[str]) – Method used for filtering (‘degree’ or ‘density’). Defaults to None.

• filter_param (float) – Parameter for the specified filtering method. Defaults to 0.0.

• filter_metric (Optional[str]) – Edge metric used for filtering. Options are ‘raw-P’ and ‘rescaled-E’. Defaults to None.

• path (Optional[str]) – Optional path to save the filtered scores and context data as CSV files. Defaults to None.

Return type:

Tuple[DataFrame, DataFrame]

Returns:

A tuple (scores_filtered, context_filtered) with the filtered scores and context data.

modina.find_flagged_variables(scores1, scores2)

Return the sorted list of variables that appear as an edge endpoint in only one of scores1/scores2 – i.e. variables flagged (single observed category, or entirely missing) in exactly one context and therefore absent from that context’s association scores.

Parameters:

• scores1 (DataFrame) – Association scores of Context 1.

• scores2 (DataFrame) – Association scores of Context 2.

Return type:

list

Returns:

Sorted list of flagged variable names.

modina.probit_rescaling(scores1, scores2, metric='rescaled-E')

modina.save_gt(groundtruths, path, mode='node', edge_magnitude=None, node_stats=None)

Write ground truth nodes or edges to a two- (or, with the optional data below, wider-) column file.

Parameters:

• groundtruths – (shift_nodes, corr_nodes, shift_corr_nodes) as returned by simulate_copula.

• path – File to write.

• mode – ‘node’ writes one row per (node, description); ‘edge’ writes one row per (edge, description), edge = ‘_’.join(sorted(pair)).

• edge_magnitude – Optional, mode=’edge’ only. Dict keyed by frozenset({node1, node2}) -> the jittered correlation magnitude injected on that edge. When given, an extra jittered_magnitude column is appended. Omit to reproduce the historical two-column file exactly (used unchanged by context_simulation_advanced.save_gt_advanced).

• node_stats – Optional, mode=’node’ only. Dict node -> (n_edges_tweaked, sum_jittered_magnitude). When given, two extra columns are appended; a node absent from the dict (e.g. mean-shift-only) is written as (0, 0.0). Omit to reproduce the historical two-column file exactly.

modina.simulate_copula(path=None, name1='context1', name2='context2', n_bi=50, n_cont=50, n_cat=50, n_samples_1=500, n_samples_2=500, n_shift_cont=0, n_shift_bi=0, n_shift_cat=0, n_corr_cont_cont=0, n_corr_bi_bi=0, n_corr_cat_cat=0, n_corr_bi_cont=0, n_corr_bi_cat=0, n_corr_cont_cat=0, n_both_cont_cont=0, n_both_bi_bi=0, n_both_cat_cat=0, n_both_bi_cont=0, n_both_bi_cat=0, n_both_cont_cat=0, shift=0.5, corr=0.7, hub_reuse_prob=0.0, binary_p_low=0.3, binary_p_high=0.7, ordinal_concentration=20.0)

Simulate two contexts with binary and continuous nodes using a Gaussian copula.

Parameters:

• path – Path to save the simulated contexts, the meta file and the ground truth information. If None, files are not saved.

• name1 – Name of the first context.

• name2 – Name of the second context.

• n_bi – Number of binary nodes to simulate.

• n_cont – Number of continuous nodes to simulate.

• n_cat – Number of categorical nodes to simulate.

• n_samples_1 – Number of samples for the first context.

• n_samples_2 – Number of samples for the second context.

• n_shift_cont – Number of continuous nodes with an artificially introduced mean shift.

• n_shift_bi – Number of binary nodes with an artificially introduced mean shift.

• n_shift_cat – Number of categorical nodes with an artificially introduced mean shift.

• n_corr_cont_cont – Number of continuous node pairs with an artifically introduced correlation difference.

• n_corr_bi_bi – Number of binary node pairs with an artificially introduced correlation difference.

• n_corr_cat_cat – Number of categorical node pairs with an artificially introduced correlation difference.

• n_corr_bi_cat – Number of binary-categorical node pairs with an artificially introduced correlation difference.

• n_corr_cont_cat – Number of continuous-categorical node pairs with an artificially introduced correlation difference.

• n_corr_bi_cont – Number of mixed node pairs with an artificially introduced correlation difference.

• n_both_cont_cont – Number of continuous node pairs with both an aritificially introduced mean shift and correlation difference.

• n_both_bi_bi – Number of binary node pairs with both an artificially introduced mean shift and correlation difference.

• n_both_cat_cat – Number of categorical node pairs with both an artificially introduced mean shift and correlation difference.

• n_both_bi_cat – Number of binary-categorical node pairs with both an artificially introduced mean shift and correlation difference.

• n_both_cont_cat – Number of continuous-categorical node pairs with both an artificially introduced mean shift and correlation difference.

• n_both_bi_cont – Number of mixed node pairs with both an artificially introduced mean shift and correlation difference.

• shift – Target magnitude of the mean shift. Each shifted node draws its actual magnitude uniformly from [shift - 0.1, shift + 0.1] (floored at 0) so ground truth effects vary in strength rather than all being identical.

• corr – Target magnitude of the correlation difference (measured as correlation coefficient between 0 and 1). Each correlated pair draws its actual magnitude uniformly from [corr - 0.1, corr + 0.1] (clipped to [0, 0.95]) so ground truth effects vary in strength rather than all being identical.

• hub_reuse_prob – Probability that a new correlation/both pair reuses an already-placed node as one endpoint (“hub”) instead of drawing two fresh nodes. Real differential networks concentrate rewiring on a few hub nodes rather than a perfect matching. When it fires, exactly one of the pair’s two slots is filled by a node that already has at least one edge; the other slot is always a fresh node, and that fresh node – plus the hub’s original first partner, the first time the hub is reused – is permanently barred from ever being reused itself. This keeps every hub isolated from every other hub, which is what makes the one cheap check below exact: a reuse is only committed if the hub’s running sum of its edges’ magnitude**2 stays below _HUB_SUMSQ_CEILING (0.95); otherwise it is abandoned and a fresh pair is drawn instead, silently, with no shrinking or retry. Default 0.0 reproduces the historical one-edge-per-node behaviour exactly.

• binary_p_low – Lower bound of the base rate drawn per binary node. How strongly two binary variables can correlate is capped by how balanced they are, so a rare node attenuates the correlation difference actually realised on its edges. Widen this range for more marginal variety, at the cost of less comparable effect sizes across edges. Use 0.0/1.0 for the historical behaviour.

• binary_p_high – Upper bound of the base rate drawn per binary node.

• ordinal_concentration – Symmetric Dirichlet concentration for the category probabilities of each ordinal node. Large values keep the categories near-balanced; 1.0 (the historical behaviour) is uniform over all splits and routinely leaves categories nearly empty.

Returns:

A tuple containing the two simulated contexts, a meta file, a list of ground truth nodes and a dict of per-edge/per-node injected effect sizes. - context1: pd.DataFrame of the first simulated context. - context2: pd.DataFrame of the second simulated context. - meta: pd.DataFrame containing the data type for each simulated variable. - ground_truth: A tuple containing three lists of ground truth nodes: (shift_nodes, corr_nodes, shift_corr_nodes). - effects: dict with ‘edge_magnitude’ (dict keyed by frozenset({node1, node2}) -> the

jittered correlation magnitude actually injected on that edge), ‘node_degree’ (dict node -> number of correlation edges touching it) and ‘node_sum_magnitude’ (dict node -> sum of jittered magnitudes over those edges). Feeds the extra columns written to ground_truth_edges.txt/ground_truth_nodes.txt when path is given, and lets a caller that writes those files itself (as the Nextflow CLI wrapper does) do the same.