ssTaxSEA() gains a reference that rare taxa cannot move.
reference = "top_k" centers each sample on its top_k (default 20)
most abundant detected taxa instead of on every taxon in the table. With
the standard CLR, losing many rare taxa (after antibiotics or
chemotherapy, for example) lowers the reference and raises the score of
every surviving taxon, so hundreds of sets can increase together with no
change among the survivors. The top-k reference is unchanged by losing
rare taxa or by adding or removing rare and empty rows, and rare taxa are
still scored. A sample with fewer than top_k detected taxa uses all of
them, so zeros never enter the reference.ssTaxSEA() gains scale = "proportion", which divides each sample by
its total and applies pseudocount as a proportion (default 1e-6).
Counts, proportions and percentages such as MetaPhlAn output all give the
same result, and the pseudocount is the same proportion in every sample
whatever its depth.scale = "counts", reference = "all",
pseudocount 0.5), so existing results are reproduced exactly.ssTaxSEA() now refuses percentages and other relative abundances on the
count scale, as it already did for proportions. Previously a MetaPhlAn
table in percent passed the check (its columns sum to 100, not 1), and
the pseudocount of 0.5, half a percent, swamped every taxon rarer than
that. Use scale = "proportion" for such tables.TaxSEA() in the README and the main
vignette: it returns All_databases plus one data frame per group of
sources, each with 6 columns, not three data frames with 5.ssTaxSEA() to the README, which did not mention single-sample
scoring at all, and corrected taxon_set_ranks() to taxon_rank_sets()
and data(TaxSEA_DB) to data(TaxSEA_db).TaxSEA() on ranked taxa and ssTaxSEA() on a
single sample. Also fixed two long-standing typos in it ("alternations",
and a missing "can be applied").The BacDive sets in TaxSEA_db have been rebuilt from a fresh, complete
harvest of BacDive: 1,776 sets covering 9,045 taxa, up from 267 sets
covering 716. Results for BacDive_bacterial_physiology will differ from
earlier releases, and code that refers to BacDive sets by name needs
updating.
Set names changed. Names no longer contain spaces and follow
BacDive_<Family>_<value>. For example:
| Before | Now |
|---|---|
| BacDive_facultative anaerobe | BacDive_Oxygen_facultative_anaerobe |
| BacDive_anaerobe, BacDive_aerobe, BacDive_microaerophile | BacDive_Oxygen_anaerobe, BacDive_Oxygen_aerobe, BacDive_Oxygen_microaerophile |
| BacDive_rod-shaped, BacDive_coccus-shaped | BacDive_Shape_rod, BacDive_Shape_coccus (and BacDive_Shape_coccoid, coccus or ovoid) |
| BacDive_Utilizes_<substrate> | BacDive_Uses_<substrate>, split by assay (below) |
| BacDive_Enzyme_alkaline phosphatase | BacDive_Enzyme_alkaline_phosphatase |
Memberships changed. Sets now contain measured BacDive data only, aggregated over every strain of each species. Membership that came from the earlier LLM-derived table is gone. For example, Faecalibacterium prausnitzii is no longer in the anaerobe set, because BacDive holds no oxygen tolerance record for it.
Substrate use is split by assay. Growing on a substrate, fermenting
it, producing acid or gas from it, reducing it, respiring it and using it
as a nitrogen source are different physiology and are now separate sets.
The former BacDive_Utilizes_nitrate mixed several of these; the nearest
equivalent is BacDive_Uses_nitrate_reduction.
Because TaxSEA compares each set against all other taxa covered by the
sets being analysed, the larger BacDive collection and the extended
NCBI_ids also shift p-values slightly for other sources. On the
bundled test data, the top-ranked metabolite-producer and
health-association sets are unchanged, with small movements in p-value
and order.
_negative), which earlier releases could not express.NCBI_ids extended with the species names of every BacDive set member,
with spaces and with underscores, including former names of reclassified
species (e.g. Bacteroides vulgatus and Phocaeicola vulgatus both map
to 821), and each member's taxid as its own name. No existing entry was
changed. Names that were present with no taxid, and so never mapped, were
filled where BacDive resolves them. This also recovers members of other
sources: taxa in TaxSEA_db with no NCBI_ids entry fell from 84 to 57.inst/extdata:
BacDive_set_provenance.tsv (per set: source family, analyte, number of
species and strains) and BacDive_build_info.tsv (harvester release,
BacDive client version, harvest dates). How the sets were built is
documented in inst/scripts/make_BacDive_sets.R; the pipeline is
https://github.com/feargalr/bacdive_harvester.TaxSEA() no longer includes BugSigDB by default; use bugsigdb = TRUE
to include it. Previously it was included automatically whenever
bugsigdbr was installed.
Why this matters: TaxSEA tests each taxon set by comparing its members
against all the other taxa covered by the sets being analysed. BugSigDB
adds thousands of signatures covering many extra taxa, so switching it on
changes that comparison for every set, not just the BugSigDB ones. The
same metabolite-producer set can get a different p-value depending on
whether BugSigDB was included, and on which BugSigDB release was
downloaded; on the bundled test data some p-values moved by as much as
0.26. Leaving it off by default keeps results reproducible and lets
TaxSEA() run offline.
TaxSEA(bugsigdb = TRUE) now warns and continues without it instead of
failing. The vignette and tests likewise skip their BugSigDB-dependent
parts, so an upstream outage no longer breaks the package build.taxsea_results$BugSigdB, which silently returns NULL; corrected to
$BugSigDB. The vignette also documented a nonexistent database
argument.get_taxon_sets() had a default argument referring to a nonexistent object,
so calling it with no argument failed with object 'taxon' not found. It
now reports the missing argument properly. It also no longer runs
unreachable code after return(), and correctly handles a lookup that
resolves to more than one NCBI ID.get_ncbi_taxon_ids() uses vapply() instead of sapply(), and qualifies
its utils calls.taxon_rank_sets() examples use \donttest rather than \dontrun.TaxSEA() gains a bugsigdb argument controlling whether BugSigDB
signatures are downloaded and included at run time.ssTaxSEA(), for ORA mode and for TaxSEA() input
validation, none of which were previously covered.NCBI_ids coverage. These document two pre-existing issues: 84 set members
have no NCBI_ids entry and are silently dropped (worst affected are
Siderophore_producers, 73 members of which 25 are usable, and the
Valles-Colomer2019 Gut-Brain Modules), and
GutMGene_producers_of_Phenylalanine appears twice, so two of its taxa
are unreachable.max_set_size in TaxSEA(), which
said 100 while the signature has been 300.ssTaxSEA() now scores each taxon set as the mean centered log-ratio
(CLR) of the set's members within a sample, replacing the previous
ranked, cohort z-scored, ssGSEA-style running-sum statistic.ssTaxSEA() returns a numeric matrix with taxon sets as rows and samples
as columns, instead of a list of two matrices oriented samples x sets.
Code written as res$scores[sample, set] becomes res[set, sample].ssTaxSEA() no longer returns p-values. The score is a descriptive
statistic; test it across samples with a test appropriate to your design.ssTaxSEA() gains a pseudocount argument (default 0.5), added to every
value before the log transform rather than only to zeros.ssTaxSEA() now works on a single sample, because the score no longer
references the rest of the cohort.ssTaxSEA() rejects proportion-like input (columns summing to 1), negative
values, non-finite values and empty samples, instead of silently producing
meaningless scores.R/TaxSEA_export.R, an outdated duplicate of an internal
function that shadowed the current version.methods import and the remaining stats/utils imports,
clearing the Bioconductor devel check warning.NCBI_ids 136 Kb to 42 Kb, TaxSEA_db
48 Kb to 35 Kb), clearing the data compression warning.R CMD check and BiocCheck
against Bioconductor devel.ssTaxSEA() function for single sample enrichment testing and documentationtaxon_rank_sets() helper with documentation and testscustom_db parameter.plotting.R file.