[parashardhapola]

Summary

This is the second of two API pull requests. The first added the conveniences that the
guides needed and changed no existing call; this one renames and moves, so that every
change of a name is checked on its own. Nothing is released yet, so the old names are
not kept.

• import cytepool gives the 56 functions and classes an analysis starts from
  (from cytepool import limma_voom, camera, meta_analysis, ...), listed with
  __version__ in cytepool.__all__ and in the package's docstring by question, the
  default first, and documented there, once each. The building blocks on arrays stay
  in cytepool.stats, the figures in cytepool.plotting, the parts of a design in
  cytepool.design, and cytepool.normalization as it is. Eight module files are
  renamed after what they compute, so that no module has a top-level function's name
  (cytepool.gsea is the function); the functions on arrays of three of them move to
  cytepool.stats: cytepool.stats.meta_analysis.fit_meta_analysis,
  cytepool.stats.sumrank.fit_sumrank and
  cytepool.stats.variance_fractions.variance_fractions.
• The gene-set tests take the data first and the sets second, as limma orders them,
  and take a result of limma_voom or limma_trend with a group and a contrast:
  camera(result, sets, id_column="symbol") tests the group's fit, which the guides
  had to rebuild by hand. roast returns one row per set, as mroast does.
• The functions that combine studies take the studies' results as one
  StudyResults, in one argument order: meta_analysis(studies),
  replication(studies, group, contrast), sumrank(studies, group, contrast) and
  held_out_prediction(studies, contrast), which, with SumRank's permutations, reads
  the cases and controls from the contrast. plot_forest(meta, feature) draws the
  studies' results that the meta-analysis keeps, and marks a study that did not
  measure the gene "not measured".
• Arguments, attributes and columns take one name per idea: "feature" for the rows of
  cubes and results ("gene" stays for gene sets and networks), df_<which>,
  <qualifier>_p_value, log2_*, sign for a number of -1 or 1, sample_groups,
  id_column for a column of ids and feature_ids for the ids of an array, the cube's
  tables as samples and groups wherever a cube is built, confidence_level and
  compression_level.

No computed number changes. An equivalence check ran the first pull request and this
branch in separate processes on the same inputs, each old call made in this branch
through the new call that replaces it and each output read in the old names: 24,388
calls, compared element by element. Every difference it found is an intended one,
checked by its rule: texts that name a renamed thing, calls that now accept None for
an option's default, refusals that name a changed argument, and calls that draw
permutations without a seed, which agree bit for bit once seeded.

Changes

Every public change, with its reason.

The top level

import cytepool now gives the 56 functions and classes an analysis starts from, listed with __version__ in cytepool.__all__ and in the package's docstring by question, the default first; before, it held only __version__. Why: the functions and classes an analysis starts from are imported from the top level, by one documented name each; the building blocks stay in cytepool.stats. The API reference documents each of them there, as cytepool.limma_voom. The modules that implement them can still be imported, except the eight renamed below.

Modules renamed

Before	After	Why
cytepool.gsea	cytepool.gene_set_enrichment	documented at the top level; the file that implements it is renamed after what it computes, so that no module has the name of a top-level function
cytepool.over_representation	cytepool.over_representation_analysis	documented at the top level; the file that implements it is renamed after what it computes, so that no module has the name of a top-level function
cytepool.principal_components	cytepool.principal_component_analysis	documented at the top level; the file that implements it is renamed after what it computes, so that no module has the name of a top-level function
cytepool.variance_partitioning	cytepool.variance_components and cytepool.stats.variance_fractions	documented at the top level; the file that implements it is renamed after what it computes, so that no module has the name of a top-level function; the functions on arrays move to cytepool.stats
cytepool.held_out_prediction	cytepool.held_out_studies	documented at the top level; the file that implements it is renamed after what it computes, so that no module has the name of a top-level function
cytepool.meta_analysis	cytepool.meta_analysis_of_studies and cytepool.stats.meta_analysis	documented at the top level; the file that implements it is renamed after what it computes, so that no module has the name of a top-level function; the functions on arrays move to cytepool.stats
cytepool.replication	cytepool.replication_across_studies	documented at the top level; the file that implements it is renamed after what it computes, so that no module has the name of a top-level function
cytepool.sumrank	cytepool.sumrank_across_studies and cytepool.stats.sumrank	documented at the top level; the file that implements it is renamed after what it computes, so that no module has the name of a top-level function; the functions on arrays move to cytepool.stats
cytepool.stats.gene_set_tests	cytepool.gene_set_tests	the gene-set tests take a differential-expression result, with a group and a contrast, so they are task functions at the top level
cytepool.stats.rotation_gene_set_tests	cytepool.rotation_gene_set_tests	the gene-set tests take a differential-expression result, with a group and a contrast, so they are task functions at the top level

Functions and classes moved or renamed

Before	After	Why
cytepool.gsea.gsea	cytepool.gsea	documented at the top level; the file that implements it is renamed after what it computes, so that no module has the name of a top-level function
cytepool.over_representation.over_representation	cytepool.over_representation	documented at the top level; the file that implements it is renamed after what it computes, so that no module has the name of a top-level function
cytepool.principal_components.principal_components	cytepool.principal_components	documented at the top level; the file that implements it is renamed after what it computes, so that no module has the name of a top-level function
cytepool.principal_components.PrincipalComponents	cytepool.PrincipalComponents	documented at the top level; the file that implements it is renamed after what it computes, so that no module has the name of a top-level function
cytepool.variance_partitioning.variance_partitioning	cytepool.variance_partitioning	documented at the top level; the file that implements it is renamed after what it computes, so that no module has the name of a top-level function
cytepool.variance_partitioning.VariancePartitioningResult	cytepool.VariancePartitioningResult	documented at the top level; the file that implements it is renamed after what it computes, so that no module has the name of a top-level function
cytepool.variance_partitioning.variance_fractions	cytepool.stats.variance_fractions.variance_fractions	a building block on arrays, in cytepool.stats with the others
cytepool.variance_partitioning.VarianceFractions	cytepool.stats.variance_fractions.VarianceFractions	the record of variance_fractions, which moves with it
cytepool.held_out_prediction.held_out_prediction	cytepool.held_out_prediction	documented at the top level; the file that implements it is renamed after what it computes, so that no module has the name of a top-level function
cytepool.held_out_prediction.HeldOutPrediction	cytepool.HeldOutPrediction	documented at the top level; the file that implements it is renamed after what it computes, so that no module has the name of a top-level function
cytepool.meta_analysis.differential_expression_meta_analysis	cytepool.meta_analysis	the short name of the default way to combine studies, which takes the studies' results as StudyResults
cytepool.meta_analysis.MetaAnalysisResult	cytepool.MetaAnalysisResult	documented at the top level; the file that implements it is renamed after what it computes, so that no module has the name of a top-level function
cytepool.meta_analysis.meta_analysis	cytepool.stats.meta_analysis.fit_meta_analysis	a building block on arrays, in cytepool.stats with the others; fit_X returns XFit, as fit_linear_model returns LinearModelFit
cytepool.meta_analysis.MetaAnalysisFit	cytepool.stats.meta_analysis.MetaAnalysisFit	the record of fit_meta_analysis, which moves with it
cytepool.meta_analysis.align_study_results	cytepool.StudyResults.table	StudyResults keeps the results with the collection they analysed, so its table needs no other input
cytepool.replication.differential_expression_replication	cytepool.replication	the short name of the default way to combine studies, which takes the studies' results as StudyResults
cytepool.replication.ReplicationResult	cytepool.ReplicationResult	documented at the top level; the file that implements it is renamed after what it computes, so that no module has the name of a top-level function
cytepool.sumrank.differential_expression_sumrank	cytepool.sumrank	the short name of the default way to combine studies, which takes the studies' results as StudyResults
cytepool.sumrank.SumRankResult	cytepool.SumRankResult	documented at the top level; the file that implements it is renamed after what it computes, so that no module has the name of a top-level function
cytepool.sumrank.sumrank	cytepool.stats.sumrank.fit_sumrank	a building block on arrays, in cytepool.stats with the others; fit_X returns XFit, as fit_linear_model returns LinearModelFit
cytepool.sumrank.SumRankFit	cytepool.stats.sumrank.SumRankFit	the record of fit_sumrank, which moves with it
cytepool.stats.gene_set_tests.camera	cytepool.camera	the gene-set tests take a differential-expression result, with a group and a contrast, so they are task functions at the top level
cytepool.stats.gene_set_tests.fry	cytepool.fry	the gene-set tests take a differential-expression result, with a group and a contrast, so they are task functions at the top level
cytepool.stats.rotation_gene_set_tests.roast	cytepool.roast	the gene-set tests take a differential-expression result, with a group and a contrast, so they are task functions at the top level
cytepool.stats.rotation_gene_set_tests.mroast	cytepool.mroast	the gene-set tests take a differential-expression result, with a group and a contrast, so they are task functions at the top level
cytepool.stats.rotation_gene_set_tests.romer	cytepool.romer	the gene-set tests take a differential-expression result, with a group and a contrast, so they are task functions at the top level
cytepool.normalization.log_cpm	cytepool.normalization.log2_cpm	the values are base-2 logarithms; log alone means natural logarithms in the layers of a cube, and the tables already say average_log2_cpm and log2_fold_change
cytepool.stats.quasi_likelihood.average_log_cpm	cytepool.stats.quasi_likelihood.average_log2_cpm	the values are base-2 logarithms; log alone means natural logarithms in the layers of a cube, and the tables already say average_log2_cpm and log2_fold_change
cytepool.plotting.plot_gene_variance_fractions	cytepool.plotting.plot_feature_variance_fractions	the rows of cubes and results are features; gene stays for gene sets and networks

Arguments renamed, added or removed

Function or class	Before	After	Why
cytepool.from_cells	samples	sample_labels	samples= is the sample table in Cube, from_bulk and every result; the cells' labels are sample_labels and group_labels
cytepool.from_cells	groups	group_labels	as sample_labels
cytepool.from_cells	sample_table	samples	the sample table, named as in Cube
cytepool.from_cells	group_table	groups	the group table, named as in Cube
cytepool.from_anndata	sample	sample_column	a column of obs, named as id_column is
cytepool.from_anndata	group	group_column	as sample_column
cytepool.from_anndata	sample_table	samples	the sample table, named as in Cube
cytepool.from_anndata	group_table	groups	the group table, named as in Cube
cytepool.from_mudata	sample_table	samples	the sample table, named as in Cube
cytepool.from_mudata	group_table	groups	the group table, named as in Cube
cytepool.write_cube	level	compression_level	a level is a value of a factor elsewhere; this one is a compression level
cytepool.io.zarr.write_array	level	compression_level	a level is a value of a factor elsewhere; this one is a compression level
cytepool.io.zarr.check_compression	level	compression_level	a level is a value of a factor elsewhere; this one is a compression level
cytepool.normalization.filter_by_expression	group	sample_groups	group means a cell type everywhere else; these are groups of samples, as in limma_voom's expression_filter
cytepool.GeneSets	source	name	as Network.name; a network's source is a regulator
cytepool.read_gmt	source	name	as Network.name; a network's source is a regulator
cytepool.stats.multiple_testing.adjust_p_values	p	p_values	as combine_p_values(p_values)
cytepool.stats.multiple_testing.proportion_of_true_nulls	p	p_values	as combine_p_values(p_values)
cytepool.stats.meta_analysis.fit_meta_analysis	level	confidence_level	a level is a value of a factor elsewhere; this one is a confidence level
cytepool.meta_analysis	results	studies	the combining functions take the studies' results as one StudyResults, which keeps the collection the results analysed, in one argument order
cytepool.meta_analysis	level	confidence_level	a level is a value of a factor elsewhere; this one is a confidence level
cytepool.replication	collection	studies	the combining functions take the studies' results as one StudyResults, which keeps the collection the results analysed, in one argument order
cytepool.replication	results	removed	the combining functions take the studies' results as one StudyResults, which keeps the collection the results analysed, in one argument order
cytepool.sumrank	collection	studies	the combining functions take the studies' results as one StudyResults, which keeps the collection the results analysed, in one argument order
cytepool.sumrank	results	removed	the combining functions take the studies' results as one StudyResults, which keeps the collection the results analysed, in one argument order
cytepool.sumrank	(new)	n_studies_summed	the number of each feature's best studies summed, as the guides choose it, in place of the proportion
cytepool.stats.sumrank.fit_sumrank	(new)	n_studies_summed	as sumrank's
cytepool.held_out_prediction	collection	studies	the combining functions take the studies' results as one StudyResults, which keeps the collection the results analysed, in one argument order
cytepool.held_out_prediction	results	removed	the combining functions take the studies' results as one StudyResults, which keeps the collection the results analysed, in one argument order
cytepool.held_out_prediction	n_genes	n_features	the rows of cubes and results are features; gene stays for gene sets and networks
cytepool.held_out_prediction	(new)	n_studies_summed	as sumrank's
cytepool.camera	y	data	a result, a VoomResult or an array
cytepool.camera	gene_ids	feature_ids	one idea, one name: id_column names the column of a cube's or a result's features whose ids are matched, and feature_ids gives the ids of an array's columns
cytepool.camera	(new)	group	the group of a result whose fit is tested
cytepool.camera	(new)	id_column	one idea, one name: id_column names the column of a cube's or a result's features whose ids are matched, and feature_ids gives the ids of an array's columns
cytepool.fry	y	data	a result, a VoomResult or an array
cytepool.fry	gene_ids	feature_ids	one idea, one name: id_column names the column of a cube's or a result's features whose ids are matched, and feature_ids gives the ids of an array's columns
cytepool.fry	(new)	group	the group of a result whose fit is tested
cytepool.fry	(new)	id_column	one idea, one name: id_column names the column of a cube's or a result's features whose ids are matched, and feature_ids gives the ids of an array's columns
cytepool.roast	y	data	a result, a VoomResult or an array
cytepool.roast	gene_ids	feature_ids	one idea, one name: id_column names the column of a cube's or a result's features whose ids are matched, and feature_ids gives the ids of an array's columns
cytepool.roast	(new)	group	the group of a result whose fit is tested
cytepool.roast	(new)	id_column	one idea, one name: id_column names the column of a cube's or a result's features whose ids are matched, and feature_ids gives the ids of an array's columns
cytepool.mroast	y	data	a result, a VoomResult or an array
cytepool.mroast	gene_ids	feature_ids	one idea, one name: id_column names the column of a cube's or a result's features whose ids are matched, and feature_ids gives the ids of an array's columns
cytepool.mroast	(new)	group	the group of a result whose fit is tested
cytepool.mroast	(new)	id_column	one idea, one name: id_column names the column of a cube's or a result's features whose ids are matched, and feature_ids gives the ids of an array's columns
cytepool.romer	y	data	a result of limma_trend, or an array
cytepool.romer	gene_ids	feature_ids	one idea, one name: id_column names the column of a cube's or a result's features whose ids are matched, and feature_ids gives the ids of an array's columns
cytepool.romer	(new)	group	the group of a result whose fit is tested
cytepool.romer	(new)	id_column	one idea, one name: id_column names the column of a cube's or a result's features whose ids are matched, and feature_ids gives the ids of an array's columns
cytepool.gsva	gene_ids	feature_ids	one idea, one name: id_column names the column of a cube's or a result's features whose ids are matched, and feature_ids gives the ids of an array's columns
cytepool.gsva	(new)	id_column	one idea, one name: id_column names the column of a cube's or a result's features whose ids are matched, and feature_ids gives the ids of an array's columns
cytepool.ssgsea	gene_ids	feature_ids	one idea, one name: id_column names the column of a cube's or a result's features whose ids are matched, and feature_ids gives the ids of an array's columns
cytepool.ssgsea	(new)	id_column	one idea, one name: id_column names the column of a cube's or a result's features whose ids are matched, and feature_ids gives the ids of an array's columns
cytepool.combined_z_scores	gene_ids	feature_ids	one idea, one name: id_column names the column of a cube's or a result's features whose ids are matched, and feature_ids gives the ids of an array's columns
cytepool.combined_z_scores	(new)	id_column	one idea, one name: id_column names the column of a cube's or a result's features whose ids are matched, and feature_ids gives the ids of an array's columns
cytepool.plage	gene_ids	feature_ids	one idea, one name: id_column names the column of a cube's or a result's features whose ids are matched, and feature_ids gives the ids of an array's columns
cytepool.plage	(new)	id_column	one idea, one name: id_column names the column of a cube's or a result's features whose ids are matched, and feature_ids gives the ids of an array's columns
cytepool.ulm	gene_ids	feature_ids	one idea, one name: id_column names the column of a cube's or a result's features whose ids are matched, and feature_ids gives the ids of an array's columns
cytepool.mlm	gene_ids	feature_ids	one idea, one name: id_column names the column of a cube's or a result's features whose ids are matched, and feature_ids gives the ids of an array's columns
cytepool.weighted_aggregate	gene_ids	feature_ids	one idea, one name: id_column names the column of a cube's or a result's features whose ids are matched, and feature_ids gives the ids of an array's columns
cytepool.propeller	f_test	f_tests	an F-test per factor: one factor or a list of them, each F-test named by its factor, as dream_voom names its F-tests
cytepool.plotting.plot_barcode	gene_ids	feature_ids	one idea, one name: id_column names the column of a cube's or a result's features whose ids are matched, and feature_ids gives the ids of an array's columns
cytepool.plotting.plot_dotplot	genes	features	the rows of cubes and results are features; gene stays for gene sets and networks
cytepool.plotting.plot_feature_variance_fractions	genes	features	the rows of cubes and results are features; gene stays for gene sets and networks
cytepool.plotting.plot_forest	studies	removed	the meta-analysis keeps the studies' results it combined (MetaAnalysisResult.study_results)
cytepool.plotting.plot_sumrank	n_labels	top	as plot_volcano(top=)
cytepool.CompositionResult	f_test	removed	the F-test tables are in tables, by factor
cytepool.StudyResults.table	collection	removed	StudyResults keeps the collection and the results; align_study_results took them
cytepool.StudyResults.table	results	removed	as collection
cytepool.MetaAnalysisResult	(new)	study_results	the studies' results it combined
cytepool.gsva	values='log_cpm'	values='log2_cpm'	the values are base-2 logarithms; log alone means natural logarithms in the layers of a cube, and the tables already say average_log2_cpm and log2_fold_change
cytepool.ssgsea	values='log_cpm'	values='log2_cpm'	the values are base-2 logarithms; log alone means natural logarithms in the layers of a cube, and the tables already say average_log2_cpm and log2_fold_change
cytepool.combined_z_scores	values='log_cpm'	values='log2_cpm'	the values are base-2 logarithms; log alone means natural logarithms in the layers of a cube, and the tables already say average_log2_cpm and log2_fold_change
cytepool.plage	values='log_cpm'	values='log2_cpm'	the values are base-2 logarithms; log alone means natural logarithms in the layers of a cube, and the tables already say average_log2_cpm and log2_fold_change
cytepool.plotting.plot_dotplot	standard_scale='gene'	standard_scale='feature'	the rows of cubes and results are features; gene stays for gene sets and networks

Attributes of results and records

Class	Before	After	Why
cytepool.stats.empirical_bayes.ModeratedFit	prior_df	df_prior	degrees of freedom are df_, as df_residual, df_total and limma's df.prior
cytepool.stats.empirical_bayes.ModeratedFit	lods	log_odds	one quantity, one plain name (limma's B): log_odds in records and tables
cytepool.stats.empirical_bayes.TreatFit	prior_df	df_prior	degrees of freedom are df_, as df_residual, df_total and limma's df.prior
cytepool.stats.empirical_bayes.SqueezedVariances	prior_df	df_prior	degrees of freedom are df_, as df_residual, df_total and limma's df.prior
cytepool.stats.dream.ModeratedFixedEffectTests	residual_df	df_residual	degrees of freedom are df_, as df_residual, df_total and limma's df.prior
cytepool.stats.dream.ModeratedFixedEffectTests	prior_df	df_prior	degrees of freedom are df_, as df_residual, df_total and limma's df.prior
cytepool.stats.dream.ModeratedFixedEffectTests	lods	log_odds	one quantity, one plain name (limma's B): log_odds in records and tables
cytepool.stats.quasi_likelihood.QuasiLikelihoodFit	prior_df	df_prior	degrees of freedom are df_, as df_residual, df_total and limma's df.prior
cytepool.stats.quasi_likelihood.QuasiLikelihoodFit	average_log_cpm	average_log2_cpm	the values are base-2 logarithms; log alone means natural logarithms in the layers of a cube, and the tables already say average_log2_cpm and log2_fold_change
cytepool.stats.quasi_likelihood.QuasiLikelihoodTest	log_fold_change	log2_fold_change	the values are base-2 logarithms; log alone means natural logarithms in the layers of a cube, and the tables already say average_log2_cpm and log2_fold_change
cytepool.stats.quasi_likelihood.QuasiLikelihoodTest	average_log_cpm	average_log2_cpm	the values are base-2 logarithms; log alone means natural logarithms in the layers of a cube, and the tables already say average_log2_cpm and log2_fold_change
cytepool.stats.mixed_models.MixedModelFit	residual_df	df_residual	degrees of freedom are df_, as df_residual, df_total and limma's df.prior
cytepool.design.checks.DesignReport	residual_df	df_residual	degrees of freedom are df_, as df_residual, df_total and limma's df.prior
cytepool.stats.voom.VoomResult	log_cpm	log2_cpm	the values are base-2 logarithms; log alone means natural logarithms in the layers of a cube, and the tables already say average_log2_cpm and log2_fold_change
cytepool.stats.combined_p_values.CombinedPValues	p_value_up	up_p_value	the qualifier goes before p_value, as in adjusted_p_value
cytepool.stats.combined_p_values.CombinedPValues	p_value_down	down_p_value	the qualifier goes before p_value, as in adjusted_p_value
cytepool.stats.combined_p_values.CombinedPValues	direction	sign	a number of -1 or 1 is a sign; direction is the text up or down everywhere else
cytepool.Activities	p_values	p_value	the name of every other record, and of its own table
cytepool.Activities	adjusted_p_values	adjusted_p_value	as p_value
cytepool.PathwayScores	samples	profiles	the two records of scores name their rows alike: profiles, with profile_id, as Activities
cytepool.GeneSets	source	name	as Network.name; a network's source is a regulator
cytepool.stats.meta_analysis.MetaAnalysisFit	level	confidence_level	a level is a value of a factor elsewhere; this one is a confidence level
cytepool.MetaAnalysisResult	(new)	study_results	the studies' results it combined, which plot_forest draws without being given them again
cytepool.CompositionResult	f_test	f_tests	the F-tests by name, each with the levels it tests; their tables are in tables and table(name), as the contrasts'
cytepool.SumRankResult	table	features	table(...) is a method everywhere else; the table has a row per feature
cytepool.ReplicationResult	genes	features	the rows of cubes and results are features; gene stays for gene sets and networks
cytepool.HeldOutPrediction	genes	features	the rows of cubes and results are features; gene stays for gene sets and networks
cytepool.PrincipalComponents	genes	features	the features used, as a table with their position in the input and the cube's feature columns, where positions alone left users to look up ids

Columns of tables

Table	Before	After	Why
differential-expression tables (limma_voom, limma_trend, dream_voom, ModeratedFit.table, StudyResults.table)	b_statistic	log_odds	one quantity, one plain name (limma's B): log_odds in records and tables
summaries of differential expression and of composition	prior_df	df_prior	degrees of freedom are df_, as df_residual, df_total and limma's df.prior
tables of fry and mroast	adjusted_mixed_p_value	mixed_adjusted_p_value	the qualifier goes before p_value, as in adjusted_p_value
replication: the table of features	direction	sign	a number of -1 or 1 is a sign; direction is the text up or down everywhere else
replication: found_in	n_genes	n_features	the rows of cubes and results are features; gene stays for gene sets and networks
replication: found_in	n_genes_same_direction	n_features_same_direction	the rows of cubes and results are features; gene stays for gene sets and networks
replication: study_pairs	n_found	n_features_found	the status words and counts of the other tables: analysed, n_features_; n_found counts studies in the table of features
replication: study_pairs	n_found_in_both	n_features_found_in_both	the status words and counts of the other tables: analysed, n_features_; n_found counts studies in the table of features
replication: studies	n_tested	n_features_tested	the status words and counts of the other tables: analysed, n_features_
replication: studies	n_found	n_features_found	the status words and counts of the other tables: analysed, n_features_
meta-analysis: studies	tested	analysed	the status words and counts of the other tables: analysed, n_features_
meta-analysis: studies	n_features	n_features_tested	the status words and counts of the other tables: analysed, n_features_
held-out prediction: auc	n_genes_up	n_features_up	the rows of cubes and results are features; gene stays for gene sets and networks
held-out prediction: auc	n_genes_down	n_features_down	the rows of cubes and results are features; gene stays for gene sets and networks
pathway scores: table()	sample_id	profile_id	the rows are profiles, as the activities' are

Settings and provenance records

Record	Before	After	Why
meta_analysis: settings and provenance	level	confidence_level	a level is a value of a factor elsewhere; this one is a confidence level
held_out_prediction: settings and provenance	n_genes	n_features	the rows of cubes and results are features; gene stays for gene sets and networks
held_out_prediction: settings and provenance	(new)	n_studies_summed	the new argument, None when the proportion is given
propeller: settings and provenance	f_test	f_tests	the F-tests, by name: a list of factor names in the settings, and the levels each tests in the provenance
GeneSets: the record of the collection	source	name	as GeneSets.name
provenance: analysis	differential_expression_meta_analysis	meta_analysis	the name of the function that made the result
provenance: analysis	differential_expression_replication	replication	the name of the function that made the result
provenance: analysis	differential_expression_sumrank	sumrank	the name of the function that made the result
settings of scores and activities: values	log_cpm	log2_cpm	the values scored, named as the argument values names them: the values are base-2 logarithms; log alone means natural logarithms in the layers of a cube, and the tables already say average_log2_cpm and log2_fold_change

Calls and outputs that changed form

Before	After	Why
camera(y, design, contrast, gene_sets, *, gene_ids=None, weights=None, ..., trend=False, robust=False); fry, roast, mroast and romer alike	camera(data, gene_sets, *, group=None, contrast=None, design=None, id_column="feature_id", feature_ids=None, weights=None, ..., trend=None, robust=None)	the data first and the sets second, as limma orders them; data is a result of limma_voom or limma_trend (its group's values, weights, design rows and contrast), a VoomResult or an array (then design and contrast are needed); trend and robust default to the result's moderation, and to False otherwise. romer refuses a result of limma_voom or a VoomResult (it takes sample weights only), and every test refuses a result of dream_voom, saying why
roast: a table of four rows, one per alternative (down, up, up_or_down, mixed), with active_proportion and p_value	roast: one row, as mroast's: n_genes, proportion_down, proportion_up, proportion_mixed, direction, p_value (two-sided, the old up_or_down), down_p_value, up_p_value, mixed_p_value	camera, fry and mroast return a row per set; the numbers are those of the old rows, and the old up_or_down proportion is the larger of proportion_down and proportion_up
differential_expression_meta_analysis(results, ...), differential_expression_replication(collection, results, group, contrast, ...), differential_expression_sumrank(collection, results, group, contrast, ...), held_out_prediction(collection, results, contrast, variable, case, control, ...)	meta_analysis(studies, ...), replication(studies, group=None, contrast=None, ...), sumrank(studies, group=None, contrast=None, ...), held_out_prediction(studies, contrast=None, *, ..., variable=None, case=None, control=None)	one input for every combining function, StudyResults, and one argument order; the group and contrast may be left out when the studies have one; meta_analysis also takes a plain mapping of results
held_out_prediction needs variable, case and control; sumrank's permutations need permute	read from the contrast when it compares two levels of one factor in every study's design (a level against the reference, or one level minus another); given explicitly otherwise	the designs and the contrast imply them
plot_forest(meta, studies, feature, ...); a study that did not measure a gene is marked not tested	plot_forest(meta, feature, ...); with StudyResults, a study that did not measure the gene is marked not measured	the results were passed twice, and the label was wrong
propeller(f_test=factor); CompositionResult.f_test, a table	propeller(f_tests=factor or list of factors); CompositionResult.f_tests, the levels each F-test compares, by name; the tables in tables and table(name)	one name and one form for F-tests, as dream_voom's
PrincipalComponents.genes: the positions of the features used	PrincipalComponents.features: a table of the features used, with position and the cube's feature columns	users need the ids of the features, not only their positions
PathwayScores.samples, and table() with sample_id	PathwayScores.profiles, which starts with profile_id, and table() with profile_id	the two records of scores name their rows alike
the activities and pathway scores take gene_ids: for a cube, the column of its features whose ids the network or the sets name, or a sequence of ids; for an array, the ids of its columns	id_column, the column of a cube's or a result's features; feature_ids, the ids of an array's columns. A cube's ids are a column of its features table: Cube.with_columns(features=...) adds one	one idea, one name: id_column names the column of a cube's or a result's features whose ids are matched, and feature_ids gives the ids of an array's columns

Other changes

• The API reference follows the top level. Each topic keeps its page; a page
  renders the method's description from the module that implements it and documents
  the top-level names of its topic, as cytepool.limma_voom, so that every name has one
  entry. cytepool.stats.meta_analysis, cytepool.stats.sumrank and
  cytepool.stats.variance_fractions are documented on the pages of their topics, and
  cytepool.__version__ on the index. The pages that explain the statistics, the
  reference pages, the site's pages and the README name the new functions, arguments
  and attributes.
• The guides use the new names and the conveniences of the first pull request: the
  imports come from the top level; the gene sets guide tests the result itself and
  builds the regulons with Network.to_gene_sets(); the pathway activity guide tests
  the scores and activities with limma; the studies guides name the aligned cell
  types (group_names), run analyse_each_study and take StudyResults.matrix; the
  quality guide draws its trend figures from the result (fit); the bulk guide reads
  edgeR's and DESeq2's calls by gene with their table() methods and draws their
  dispersions; the pool cells guide pools an arbitrary set of samples with
  Cube.with_columns; the repeated-measures guide filters both models by the
  condition, expression_filter={"sample_groups": "condition"}, so that they test the
  same genes, and says why.
• Labels of MDS and PCA plots stay inside the frame and apart. With labels=True,
  each sample's label goes above its point, moves in where it would cross the frame and
  up where it would overlap another, with a line to its point when it moved, as
  plot_sumrank places its labels. A PCA plot, drawn to one scale along both axes,
  widens where the labels need room above, so that no sample leaves the frame. The
  quality guide's MDS plot had a label across the frame and labels on top of each
  other. The labels keep the samples' order and their points.
• table() names F-tests only when a result has some. A result of several
  contrasts without F-tests says "the result has 3 contrasts; name one with contrast",
  where differential expression said "contrasts and F-tests" whatever it held.
• romer's refusal of weights with a result names arrays only, since romer takes no
  VoomResult.

Choices, and why

• roast's row has no gene_set column. roast tests one set, given as a list of
  ids, which has no name; its row has the columns of mroast's otherwise, and mroast
  names its sets.
• propeller(f_tests=) takes a factor or a list of factors, each F-test named by
  its factor, and dream_voom(f_tests=) keeps its mapping of names to contrasts. A
  mapping of contrasts for propeller, and a factor for dream_voom, would test
  hypotheses that neither function tests today, which need validation of their own
  against speckle and variancePartition; this pull request changes no number.
• A cube's ids come from a column of its features table, which id_column names
  for the scores, the activities and the gene-set tests alike; feature_ids gives the
  ids of an array's columns. A cube took a sequence of ids too, which is refused now
  with the way to add a column, Cube.with_columns(features=...).
• compression_level everywhere a compression level is given: also
  cytepool.io.zarr.write_array and check_compression, which write_cube passes it
  to, so that one idea keeps one name down to the file format.
• fit_sumrank takes n_studies_summed, as sumrank and held_out_prediction
  do, so that the number of studies summed is given alike at both levels.
• Options that a result or the studies imply default to None. The gene-set tests'
  trend and robust take the result's moderation (False for an array), and the
  group, the contrast and the variable a permutation shuffles are read from the
  studies' results when they hold one; None given for them was refused before.
• The meta-analysis keeps the studies' results it combined
  (MetaAnalysisResult.study_results), which plot_forest draws. It tells "not
  measured" from "not tested" only for a StudyResults, whose collection records what
  each study measured; for a plain mapping of results it says "not tested", as before.
• The gene-set tests of a result pass the contrast's weights on the design columns
  the group's fit kept, as a named contrast of a rank-deficient group is tested in
  limma_voom, and take the trend and robust settings of the result's moderation by
  default; for an array they default to False, as before.
• The modules that implement top-level names stay importable, except the eight
  renamed ones, but document nothing themselves: cytepool.cube and cytepool.io
  re-export their names for code that imports them there, with an empty __all__, and
  cytepool.design lists its parts but not Design.
• Reprs and messages keep their words except where they name a renamed function,
  argument, attribute or column (PathwayScores(n_profiles=...),
  PrincipalComponents(n_features=...), GeneSets with its name), so that the
  guides print what they printed; the language pull request applies the copy rules to
  every text at once.
• The figures plot_significant_genes and plot_replicated_genes keep their
  names: they draw genes found, as their pages call them, and renaming figures was
  outside the plan.

Validation

Equivalence check. The first API pull request (8afa32a) and this branch ran in
separate processes, each in its own environment, on the same inputs: every public entry
point with its valid call, the inputs of every validation script built from the same
seeds with the calls the scripts make, and edge cases. The inputs call the API as the
first pull request names it. In this branch's process each changed call went through an
adapter to the new call, written from the list of changes above, and each output was
read in the old names (classes, attributes, columns, settings and the names of
analyses), so that both outputs were compared at the same places, element by element,
NaN equal to NaN and any other difference measured in units in the last place. Every
call's arguments were kept, to compare the inputs of calls that take objects with
renamed parts. The intended differences, each with the rule that checks it, were
written down before any result was read; three that the first run found were added
afterwards with their rules, each a consequence of a change listed above (the last
three rows of the table).

• 24,388 calls in 10,471 cases, 826,881 output parts with 183,085,849 elements; 3,421
  differences in 1,073 calls, each explained:

  Intended difference	Differences	How it was checked
  texts that name a renamed function, argument, attribute or column: messages, warnings, 416 reprs and 45 cube histories	836, in 775 calls	the same exception or warning class, and the old text equal to the new one once the renamed words of the list of changes are put in, token by token; four messages reworded with their argument (the missing labels of filter_by_expression's sample_groups, the scores' genes not found, and what the gene-set tests and propeller(f_tests=) accept) by their own pairs of old and new words
  the arguments of calls that take objects with such texts	257 calls	with the arguments kept and read in the old names, every argument that differs is such a text; a table passed to a figure is read with its renamed columns under their old names
  calls that the first pull request refused for an argument None, which now gives the default: trend and robust of camera, fry, roast and mroast; group, contrast, proportion_of_studies and permute of the combining functions	17 calls (2,247 differences: their outputs)	each output equals, digest for digest, that of the entry point's valid call, which gives the argument the value None stands for; SumRank on arrays, whose valid call sums half the studies, was made with the default in the first pull request and with None here: its 13 fields identical
  a cube's gene_ids is id_column	21 calls (42)	each wrong value refused with the same exception, the message naming id_column
  held_out_prediction given one of variable, case and control as None, with the other two	3 calls (6)	refused before as not a string (TypeError), and now because the three are given together or not at all (ValueError)
  calls that draw permutations without a seed: gsea of a result, weighted_aggregate of a cube or a result, and their edge cases	10 calls (33)	made again with rng=1 in both trees: their 46 output arrays identical

  roast's adapter rebuilt the first pull request's table of four rows from the new
  row, each value taken unchanged from its column and the up_or_down proportion the
  larger of proportion_down and proportion_up: the rebuilt tables equal the old ones,
  bit for bit. The parts that only this branch has were set aside and counted, 442 in
  all: the studies' results a meta-analysis keeps, propeller's F-tests by name, the
  profile_id column of pathway scores, the columns of the principal components'
  table of features other than position (which holds the old positions, compared),
  and the setting n_studies_summed of held-out prediction. No part of the first pull
  request's outputs was set aside.

• Not compared, in either tree: the inputs of validation/sumrank.py, whose script
  imports scikit-learn, which the environments lack (SumRank's entry points and edge
  cases are compared). A figure is compared by its axes' labels; its drawing is checked
  by the tests and by eye below. The PCA plot's widening for labels came after the
  check; it changes no computed value, and the tests below check it.

Inventory. Every public callable of the first pull request's inventory (263 in the
three groups of tests/test_masked_inputs.py, with 1,037 arguments) is unchanged or
named in the list of changes above: 31 callables and 58 arguments renamed, moved or
removed, each listed.

Validation scripts. Every script in validation/ was updated to the new names and
run on both trees with the same reference environments. 29 print exactly the first
pull request's output; the other 9 differ only in times they measure (distributions,
pool_cells, cube_reads, negative_binomial_fits, quasi_likelihood,
interferon_stimulated_pbmcs, whose peak memory and version line differ too), in two
check names of sumrank that now name fit_sumrank, and in the path and line of a
warning or a traceback that the edits moved (combined_p_values_and_replication,
anndata_conversion). No value, tolerance or verdict changed. anndata_conversion
stops in both trees at its LIANA reference, which no environment here has, after
pooling, exporting and running the scanpy and decoupler references with the new
arguments. The fixtures in tests/data are unchanged (--write-fixtures was not run;
the scripts still write the keys the tests read).

Pages. All 15 notebooks were rewritten and executed again, and every code cell's
printed text was compared with the outputs before this change: every number the same,
except the repeated-measures guide, whose limma-voom model now filters by the
condition as the dream model does (3,651 genes tested instead of 5,125, 2,536 called
instead of 3,168; 2,456 called by both instead of 2,273, with the same correlation of
0.999). Texts differ where they name renamed things: the gene sets' name: (with the
network's file and digest, which to_gene_sets keeps), the aligned cell types' names
in "Combine studies", a cube's history ("the rows of the sample table given"), and the
line of code that gsea's warning quotes. Both π₁ lines of the replication guide are
unchanged, as that page had been executed with the λ = 0.5 default already, and
roast's p-value in "Gene sets" is the same number, read from up_p_value. All 42
figures were looked at, against the 41 before: 34 are identical. Of the others, three
name the aligned cell types instead of their ontology ids, the forest plot of "Combine
studies" marks the study that did not measure the gene "not measured", the dot plot's
colour bar says "scaled per feature", the bulk guide's figure of dispersions is new,
the quality guide's MDS plot has its labels inside the frame and apart, and the pool
cells guide's second PCA plot has other ticks on its y-axis, as its legend is now
placed once the plot has its scale. No legend covers a point, a line or a label, and
every label and count is inside its frame. make -C docs check-outputs passes on all
15.

Tests

• The tests of the first pull request are renamed with the list of changes, with no
  tolerance changed; the two that imported renamed modules import the new files.
• New tests, 25 functions in 10 files, each checked against something independent of
  the code under test: the top level against its docstring and the modules that
  implement each name, and importing it loads no optional library; camera, fry, roast,
  mroast and romer of a result against the same test of the group's voom values or
  log2 CPM, weights, design rows and contrast passed by hand, with the ids of a column;
  their refusals of a dream-voom result and of a design, weights or ids given with a
  result, and romer's of voom's observation weights; held_out_prediction reading the
  cases from the contrast against the explicit variable, case and control, and a
  contrast that compares no two levels needing them; SumRank's n_studies_summed
  against the proportion that gives it, its permutations of the factor the contrast
  compares against permute given, and the group and contrast left out for studies
  that have one, also for replication; the meta-analysis of a StudyResults against
  that of its results; plot_forest telling a study that did not measure a gene from
  one that left it out; propeller's F-tests of two factors against each factor's
  alone; the principal components' table of features against their positions and the
  cube's columns; and the labels of MDS and PCA plots, after the final draw, inside the
  frame, apart and on their points, with every sample inside the frame, which fails on
  the previous placement.
• tests/test_masked_inputs.py classifies every renamed, moved and new callable and
  argument; tests/test_documentation.py knows that a top-level name is documented at
  the top level and that a module's description may be rendered without its members;
  tests/test_private_names.py follows the moved files; and
  docs/coverage_exemptions.toml follows the renames.
• uv run pytest -q --durations=15: 5156 passed, 18 skipped (zstd needs Python 3.14).
• Rounding changed (OPENBLAS_CORETYPE=Sandybridge, 4 threads,
  NUMBA_CPU_NAME=generic, a fresh cache): 5156 passed, 18 skipped.
• ruff check, ruff format --check and mypy pass; make -C docs api and
  make -C docs html build without a warning.