Initialize a phyloDS Experiment — newExperiment • phyloDS

Creates an experiment object containing all metadata required for phylogenetic differential splicing analysis. This is the entry point for any phyloDS workflow.

Usage

newExperiment(
  sampleInfo,
  speciesInfo,
  orthogroups,
  dnaDir,
  msaDir,
  speciesTree,
  requireUltrametric = TRUE,
  ultrametricTol = 1e-06
)

Arguments

sampleInfo

data.frame or character. Sample metadata table (or path to tab-delimited file) with required columns:

sampleID: Unique identifier for each RNA-seq sample.
speciesID: Species identifier matching speciesInfo.
bam: Path to the aligned BAM file.
strandSpecific: Library strandedness: 0 = unstranded, 1 = stranded (read 1 on the transcript strand), 2 = reversely stranded (read 1 antisense, e.g. dUTP or Illumina TruSeq Stranded).
isPairedEnd: Logical. TRUE for paired-end sequencing.

speciesInfo

data.frame or character. Species metadata table (or path to

tab-delimited file) with required columns:

speciesID: Unique species identifier.
genome: Path to reference genome FASTA file.
group: Group assignment: "1" (background) or "2" (foreground/test). The differential splicing test evaluates changes along the branch(es) leading to group 2 species

Optional columns: annotation (path to GTF/GFF file).

orthogroups

data.frame or character. Orthogroup definitions (or path to tab-delimited file) with required columns:

geneID: Gene identifier (unique within species).
orthogroupID: Orthogroup identifier grouping homologous genes.
speciesID: Species identifier matching speciesInfo.
seqid: Chromosome or scaffold name.
chromStart: Gene start position.
chromEnd: Gene end position.
strand: Strand: "+" or "-".

Orthogroups must be 1-to-1: exactly one gene per species per orthogroup. All species in speciesInfo must be represented.

dnaDir

Character. Directory path for storing extracted DNA sequences. Created if it does not exist.

msaDir

Character. Directory path for storing multiple sequence alignments. Created if it does not exist.

speciesTree

phylo object or character. Species phylogeny as an ape::phylo object or path to a Newick tree file. Required. Tip labels must exactly match speciesID values in speciesInfo. The tree must carry branch lengths.

requireUltrametric

Logical. If TRUE (default), the species tree must be ultrametric (all tips equidistant from the root), as expected when comparing extant taxa under phylogenetic comparative models. Set to FALSE to allow non-ultrametric trees (e.g. additive/phylogram trees).

ultrametricTol

Numeric. Tolerance passed to is.ultrametric when requireUltrametric = TRUE. A small positive value absorbs the rounding error introduced when a tree is written to / read from Newick with limited decimal precision. Default: 1e-6.

Value

A list (experiment object) with components:

sampleInfo

data.frame. Sample metadata merged with group assignments. Contains all input columns plus group as a factor.

speciesInfo

data.frame. Species metadata as provided.

speciesTree

phylo object. Parsed species phylogeny.

orthogroups

GRanges object. Orthogroup genomic coordinates with metadata columns geneID, orthogroupID, and speciesID.

dirs

list. Absolute paths to working directories:

dna: DNA sequence storage
msa: Multiple alignment storage

Details

This function performs the following steps:

Reads input tables from files or validates provided data.frames.
Validates that all required columns are present.
Checks consistency between tables (e.g., all sample species exist in speciesInfo).
Parses the species tree if provided as a file path, and checks that it has branch lengths and (optionally) is ultrametric.
Converts orthogroups to a GRanges object for genomic operations.
Creates output directories if they do not exist.

Input File Formats

All input tables can be provided as tab-delimited text files with headers. Example sampleInfo.tsv:


sampleID    speciesID       bam                         strandSpecific  isPairedEnd
human_rep1  Homo_sapiens    data/human_rep1.bam        2               TRUE
human_rep2  Homo_sapiens    data/human_rep2.bam        2               TRUE
mouse_rep1  Mus_musculus    data/mouse_rep1.bam        2               TRUE

Example speciesInfo.tsv:


speciesID       genome                      group   annotation
Homo_sapiens    genomes/human.fa           1       annot/human.gtf
Mus_musculus    genomes/mouse.fa           2       annot/mouse.gtf