Results of several studies

Results of several studies#

Studies of one question are compared or combined once each is analysed on the collection’s axes: its aligned cube, with a design built from its own samples. analyse_each_study() runs limma_voom(), limma_trend() or dream_voom() on every study of a CubeCollection that way, with one formula, its levels and contrasts. StudyResults keeps the results with their collection: it lines them up gene by gene, with the reason a study has no value for a gene, and gives one column of every study, such as the p-values, as a studies x genes matrix, the form that combined p-values and SumRank take. meta_analysis(), replication(), sumrank() and held_out_prediction() take it.

The differential expression of every study of a collection, analysed alike.

Studies of one question, such as cohorts of a disease, are compared or combined only once each is analysed on the collection’s axes: its aligned cube (aligned_cube()), with a design built from its own samples. analyse_each_study() runs one analysis per study that way, and StudyResults keeps the results with their collection: it lines them up feature by feature (table()), with the reason a study has no result for a feature (it did not measure it, did not test it, or did not analyse the group or contrast), and gives one column of every study as a studies x features matrix (matrix()), the form that combined p-values (combine_p_values()) take. Every function that combines studies takes it: meta_analysis(), replication(), sumrank() and held_out_prediction().

Memory:

Each result keeps the cube it analysed (see DifferentialExpressionResult), here the study’s aligned cube. The aligned cube of a cube read with read_cube() stays on disk; that of a cube in memory, when its groups or features are selected or renamed, holds a copy of the study’s values, which the results keep for as long as they exist.

cytepool.analyse_each_study(collection, formula, *, analysis=limma_voom, random=None, levels=None, contrasts=None, **options)#

Analyse every study of a collection alike, each on its aligned cube.

For each study, in the collection’s order: its aligned cube (aligned_cube()), a Design built from the cube’s own samples with the formula, random effects, levels and contrasts given, and analysis of the cube with that design and options. The loop a meta-analysis or a replication analysis starts from, in one call: analyse_each_study(collection, "~ condition", levels={"condition": ["control", "case"]}, contrasts={"case_vs_control": "conditioncase"}). A study whose design or analysis fails stops the run, with a note that names the study.

Parameters:

  • collection – The studies, aligned.

  • formula – The design’s formula, such as "~ condition", over the columns of each study’s sample table.

  • analysis – limma_voom() (by default), limma_trend() or dream_voom().

  • random – The design’s random effects, such as "(1 | donor)", for dream_voom.

  • levels – The levels of the design’s factors, the reference first, such as {"condition": ["control", "case"]}.

  • contrasts – The design’s named contrasts, such as {"case_vs_control": "conditioncase"}.

  • **options – The options of analysis, such as groups, prior_weights or expression_filter.

Returns:

The result of every study, with the collection.

Raises:

  • TypeError – If collection is not a CubeCollection, formula not a string, or analysis not one of the three.

  • ValueError, KeyError – As Design and analysis raise them for a study, with a note that names the study.

Used in: Combine studies, Replication across studies

Explained in: The cube and its additive layers, Meta-analysis

class cytepool.StudyResults(collection, results)#

The differential-expression result of every study of a collection.

A read-only mapping of study name to result, in the order of the collection’s studies, with the collection the results analysed. Each result is the analysis of the study’s aligned cube, such as analyse_each_study() makes, so that its groups are the collection’s aligned groups and its features those the study measured. Immutable.

Parameters:

  • collection – The collection whose aligned cubes the results analysed.

  • results – The result of every study of the collection, by study name, from limma_voom(), limma_trend() or dream_voom().

Raises:

  • TypeError – If collection is not a CubeCollection, results not a mapping, or a result not a DifferentialExpressionResult.

  • ValueError – If results does not give the result of every study of the collection, and no other.

Used in: Combine studies, Replication across studies

Explained in: The cube and its additive layers, Meta-analysis

property collection#

The collection whose aligned cubes the results analysed.

property studies#

The study names, in the collection’s order.

property designs#

The design each study’s result analysed, by study name (read-only); None for a result built without one.

property summary#

The summary of every study’s result, one after another, with study first: one row per study and group, with the status, samples, features and degrees of freedom of the group’s fit. A column that some studies’ summaries lack, such as dream’s df_method, is missing in their rows.

table(group=None, contrast=None)#

Line up the studies’ results of one group and contrast, feature by feature.

The table has a row for every study and every feature of the collection: the studies in order, and the features in the collection’s order within each study, as matrix() lays them out. status says whether the study tested the feature, and why not:

  • "tested": the study’s table of the group and contrast has the feature;

  • "not_tested": the study measured the feature and has a table of the group and contrast, without the feature, as when its expression filter left it out;

  • "not_measured": the study did not measure the feature (CubeCollection.measured), so no analysis of it could test it;

  • "not_analysed": the study measured the feature but has no table of the group and contrast: it does not have the group, its result leaves the group out, the group was not fitted, or the contrast cannot be estimated from its samples; reason says which, in the words of the study’s result.

The columns are study, feature_id, symbol (when the collection’s features have it), status, reason (empty where tested), and then the numeric columns of the studies’ tables, such as log2_fold_change, standard_error, t, p_value and adjusted_p_value, in the order in which the studies first have them, NaN where a study did not test the feature. A missing feature is thus never a zero, and a feature that a study did not measure is told apart from one that it measured and left out.

Parameters:

  • group – An aligned group id; it may be left out when the studies analysed one group.

  • contrast – A contrast name, or the name of an F-test of dream_voom(); it may be left out when the studies tested one.

Returns:

A table of collection.n_studies * collection.n_features rows.

Raises:

  • ValueError – If a key is left out and the studies analysed several, or a study’s result did not analyse its aligned cube: it analyses a group that the study does not have in the collection, or tests a feature that the study did not measure there.

  • KeyError – If group is not a group of the collection, or no study tested contrast.

  • TypeError – If a key is not a string.

Used in: Combine studies

Explained in: The cube and its additive layers, Meta-analysis

matrix(column, group=None, contrast=None)#

Return one numeric column of every study, studies x features.

The rows are the collection’s studies and the columns its features, in its order (collection.features), as table() lines them up: for example the p-values of every study, as combine_p_values() takes them, or the t-statistics. A feature that a study did not test is NaN.

Parameters:

  • column – A numeric column of the studies’ tables, such as "p_value", "t" or "log2_fold_change".

  • group – An aligned group id; it may be left out when the studies analysed one group.

  • contrast – A contrast name; it may be left out when the studies tested one.

Returns:

A read-only float64 array of shape (n_studies, n_features).

Raises:

  • KeyError – If no study’s table has the column, group is not a group of the collection, or no study tested contrast.

  • ValueError – If the column is not numeric, or a key is left out and the studies analysed several.

  • TypeError – If an argument is not a string.

Used in: Combine studies, Replication across studies