# Bioconductor Treesummarizedexperiment

> TreeSummarizedExperiment has extended SingleCellExperiment to include hierarchical information on the rows or columns of the rectangular data.

- Skill: `biomate-ai/bioconductor-treesummarizedexperiment` (Agent Skill)
- Install (CLI): `npx skillmds@latest add biomate-ai/bioconductor-treesummarizedexperiment`
- Raw SKILL.md: https://api.skillmd.com/api/skills/biomate-ai/bioconductor-treesummarizedexperiment/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: biomate-ai (https://skillmd.com/u/biomate-ai)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/biomate-ai/bioconductor-treesummarizedexperiment

---


# TreeSummarizedExperiment

## Dependencies & Environment

> Package-intrinsic requirements from the Bioconductor landing page — reproduce in any R environment.

- **Version:** 2.20.0 · **Bioconductor:** 3.23 · **R:** ≥ 4.6
- **Depends:** SingleCellExperiment, S4Vectors, Biostrings
- **Imports:** BiocGenerics, ape, rlang, dplyr, SummarizedExperiment, BiocParallel, IRanges, treeio
- **System requirements:** URL
- **Install:** `BiocManager::install("TreeSummarizedExperiment")`

## When to Use
- Storing rectangular experimental data alongside hierarchical tree structures using the `TreeSummarizedExperiment` class.
- Aggregating data to different taxonomic levels (e.g., phylum or class) using `aggTSE`.
- Subsetting data by specific tree nodes or leaves using `subsetByNode`.
- Storing reference sequence data per feature using the `referenceSeq` slot.

## When NOT to Use
- For standard single-cell RNA-seq without hierarchical relationships, use `SingleCellExperiment` because the tree-related slots and overhead are unnecessary.
- For purely manipulating or visualizing phylogenetic trees without rectangular assay data, use `ape` or `ggtree` directly because they are specialized for tree operations.

## Data Requirements
- An `assays` matrix representing observed data (e.g., counts) with rows as entities and columns as samples.
- `rowData` and `colData` data frames for feature and sample annotations.
- Hierarchical structures provided as `phylo` objects for `rowTree` and/or `colTree`.
- Link information mapping assay rows/columns to tree nodes via `rowNodeLab` or `colNodeLab`.
- Optional reference sequences as `DNAStringSet` or `DNAStringSetList`.

## Key Parameters
- **rowTree**: A `phylo` object representing the hierarchical structure on the rows of the assays.
- **rowNodeLab**: A character vector linking the rows of the assays to the node labels of the `rowTree`.
- **colLevel**: The desired aggregation level for columns in `aggTSE`, specified via node label or node number.
- **rowFun**: The aggregate function (e.g., `sum`) applied to the row dimension in `aggTSE`.
- **only.leaf** (TRUE): Logical in `findDescendant` to specify if only leaf descendants should be returned.
- **rowFirst** (FALSE): Determines the aggregation order in `aggTSE` when aggregating both dimensions.
- **colDataCols**: Specifies which columns of `colData` to keep in the final output of `aggTSE`.

## Best Practices
- Use `toTree` to convert a taxonomic `data.frame` into a `phylo` object before adding it to the object.
- Use `changeTree` to replace an existing tree and update the mapping if nodes are labeled differently.
- Use `aggTSE` with `colDataCols` to speed up aggregation by dropping irrelevant column data.
- Avoid modifying `rowLinks` or `colLinks` manually to prevent breaking the link between assays and trees.

## Common Pitfalls
- **Missing node labels**: Row or column names in the assay do not match the node labels of the tree, causing them to be removed with warnings. Fix: Provide the correct mapping via `rowNodeLab` or `colNodeLab` during construction.
- **Broken links after pruning**: Subsetting a tree with `ape::keep.tip` changes node numbers and breaks links. Fix: Use `trackNode` to track alias labels and update the `LinkDataFrame` accordingly.
- **Failed tree replacement**: Replacing a tree directly with `rowTree<-` fails if names cannot be matched. Fix: Use `changeTree` with `rowNodeLab` when labels differ between the object and the new tree.

## Alternatives
- **SingleCellExperiment**: For storing single-cell data without hierarchical tree structures.
- **ape**: For general phylogenetic tree manipulation without associated rectangular assay data.
- **ggtree**: For visualizing phylogenetic trees, which `TreeSummarizedExperiment` relies on for plotting rather than implementing itself.

## Citations
- Huang R, et al. (2021). TreeSummarizedExperiment: a S4 class for data with tree structures. *F1000Research*.
- Lun and Risso (2020). SingleCellExperiment.

## References
- Homepage: https://bioconductor.org/packages/TreeSummarizedExperiment
- Vignette: https://bioconductor.org/packages/release/bioc/vignettes/TreeSummarizedExperiment/inst/doc/Introduction_to_treeSE.html

<!-- biomate-cta -->
---

## Run this on BioMate

This skill is the **knowledge layer** — when, why, and how to use `treesummarizedexperiment`. To **run this analysis on your own data** with managed compute, automated QC, and reproducible outputs, use **[BioMate](https://www.biomate.ai?ref=kb&pkg=treesummarizedexperiment)** — free to start.

▶ **[Open `treesummarizedexperiment` on BioMate →](https://www.biomate.ai?ref=kb&pkg=treesummarizedexperiment)**