twinfer.inference.covariance_decomposition_z_scores.infer_with_twinfer

twinfer.inference.covariance_decomposition_z_scores.infer_with_twinfer(table, genes, time_points=None, scenario='auto', seed=101010, split=(1, 1, 2), regulators=None, targets=None, chunk_x=100, chunk_y=300, z_thresholds=(1.96, 2.326, 1.96), n_permutations=1000, correction='auto', fdr=0.05, cross_correlation_pairs='all', save_to=None)[source]

Score gene pairs with the covariance decomposition (and the cross-time correlation when there are several time points).

Parameters:

  • table (pandas.DataFrame) – Twin-pair scenarios: clone_id, replicate (1 and 2 = the two sisters), time_step and one column per gene. “clones” scenario (real data): one row per cell with clone_id, the genes (values used as given, e.g. CP10k) and optionally time_step.

  • genes (list of str) – Gene columns. Pairs (X, Y) with X before Y in the list are scored; in the “clones” scenario regulators x targets are scored instead when given.

  • time_points (list, optional) – Time steps to use. Twin-pair scenarios: one value -> “single_time_point”, several -> “multiple_time_points”. “clones”: optional, selects the single time step of the cells.

  • scenario (str) – “auto” (default: “clones” when the table has no replicate column, otherwise by the number of time points) or one of SCENARIOS.

  • seed (int, tuple) – Random split of the clones for “multiple_time_points”: seed and proportions of (twins at t_a, twins at t_b, cross group).

  • split (int, tuple) – Random split of the clones for “multiple_time_points”: seed and proportions of (twins at t_a, twins at t_b, cross group).

  • regulators (list of str, list of str, int, int) – “clones” only: gene lists of the pairs to score and the block sizes of the computation.

  • targets (list of str, list of str, int, int) – “clones” only: gene lists of the pairs to score and the block sizes of the computation.

  • chunk_x (list of str, list of str, int, int) – “clones” only: gene lists of the pairs to score and the block sizes of the computation.

  • chunk_y (list of str, list of str, int, int) – “clones” only: gene lists of the pairs to score and the block sizes of the computation.

  • z_thresholds (tuple of float) – (z_rho, z_rho_s, z_rho_Delta) significance thresholds of classify_inference_scenario (adds the column inference_scenario).

  • n_permutations (int) – “multiple_time_points”: permutations of the cross group for the p-value of delta = |rho_dag_xy| - |rho_dag_yx|; each null value is built the same way from the permuted correlations, p = (1 + #{|null| >= |delta|}) / (n + 1).

  • correction ({"auto", "bh", "none"}, float) – Multiple testing of z_rho in the inference scenario: “bh” = Benjamini-Hochberg over all pairs of the result, z_rho significant when q_rho <= fdr, and z_rho_Delta BH over the pairs with significant z_rho, significant when q_rho_Delta <= fdr (adds the columns q_rho, q_rho_Delta; with several time points with the suffix _ta / _tb); “none” = the |z| thresholds. “auto” (default): “bh” for the “clones” scenario (real data, many pairs), “none” for the twin-pair scenarios (one pre-specified pair per simulated system). z_rho_s always uses its threshold.

  • fdr ({"auto", "bh", "none"}, float) – Multiple testing of z_rho in the inference scenario: “bh” = Benjamini-Hochberg over all pairs of the result, z_rho significant when q_rho <= fdr, and z_rho_Delta BH over the pairs with significant z_rho, significant when q_rho_Delta <= fdr (adds the columns q_rho, q_rho_Delta; with several time points with the suffix _ta / _tb); “none” = the |z| thresholds. “auto” (default): “bh” for the “clones” scenario (real data, many pairs), “none” for the twin-pair scenarios (one pre-specified pair per simulated system). z_rho_s always uses its threshold.

  • cross_correlation_pairs ({"all", "significant_rho", "regulation"}) – “multiple_time_points”: which gene pairs get the cross-time correlation (z_dag_xy, z_dag_yx, delta, p_delta): “all” (default) every pair; “significant_rho” pairs whose z_rho is significant at t_b; “regulation” pairs in inference scenario 2 or 3 at t_b. The other pairs get NaN in these columns (and skip the permutations).

  • save_to (str, optional) – Path to save the result table (.csv, .csv.gz, .tsv, .tsv.gz or .parquet). The settings of the call (genes, time points, scenario, split, seed, thresholds, correction, permutations, cross-correlation pairs, date) are written next to it as <name>_settings.json. See save_result.

Returns:

One row per gene pair (and time pair). Columns: gene_x, gene_y, t_a, [t_b,] the N of each group and the statistics. One time point: STAT_COLUMNS. Several time points: for each of t_a and t_b (suffix _ta / _tb) the clone-size statistics (rho, S, C, U, rho_Delta, h_x, h_y, sigma_rho, sigma_C, sigma_D, z_rho, z_rho_s, z_rho_Delta) of ALL cells measured at that time: z_rho uses the twin pairs of that group (N_a / N_b, each a clone of 2) and the cross-group sister measured then (N_cross singletons), N_clones_ta / N_clones_tb in total; z_rho_s and z_rho_Delta use the twin pairs. Then rho_dag_xy, rho_dag_yx, z_dag_xy, z_dag_yx, delta (= rho_dag_xy - rho_dag_yx) and p_delta (its permutation p-value). Clones: rho, S, C, U, rho_Delta, h_x, h_y, sigma_rho, sigma_C, sigma_D, z_rho, z_rho_s, z_rho_Delta. Every scenario adds inference_scenario (q_rho, q_rho_Delta with correction=”bh”). A gene without variance gives NaN in the statistics of its pairs (and in the cross-time columns, including p_delta).

Return type:

pandas.DataFrame