Dowser
B-cell receptor phylogenetics in the Immcantation framework
Accepts:CSVTSVRDARDS
What it does
Dowser is an R package in the Immcantation framework for reconstructing and analysing B-cell receptor (BCR) phylogenies. It builds lineage trees from BCR sequences, reconstructs germline and intermediate (internal-node) sequences, and statistically tests for evidence of B-cell evolution, migration and differentiation.
It accepts AIRR-formatted data and Change-O clone tables, supports several tree-building algorithms — maximum parsimony, maximum likelihood, and the immunoglobulin-specific IgPhyML — and can analyse paired heavy/light chains.
- Multiple tree builders: pratchet, pml, dnapars, dnaml, IgPhyML and RAxML
- Germline and intermediate (internal-node) sequence reconstruction
- Discrete trait analysis (migration, differentiation, isotype switching)
- Measurable-evolution / time-resolved analysis
- Paired heavy/light chain support
- Publication-quality lineage visualisations
Accepted input types
| Input type | What the framework does with it |
|---|---|
| TSV | AIRR / Change-O clone table (tab-separated), used directly as the clone table. Enable column mapping if your headers differ from the canonical AIRR keys. |
| CSV | The same AIRR / Change-O clone table in comma-separated form; converted to the canonical table before the R service runs. |
| RDA / RDS | Saved R data objects containing the clone/AIRR data, loaded directly by the R service.⚠ NEEDS VERIFICATION |
Form fields
Every field shown in this method's form, generated from the package's field definitions so it always matches the live form. The mapping column is filled only where a field corresponds clearly to a native method parameter.
Input Mapping
| Field | What it is / used for | Allowed values | Default | Maps to method parameter | Visible when |
|---|---|---|---|---|---|
Enable input column mapping doMapping | When true, map uploaded table headers to canonical Dowser AIRR keys before running. | Yes / No | No | N/A (wrapper-specific) | Always |
Sequence ID column column_map.sequence_id | — | text | — | N/A (wrapper-specific) | Shown when Enable input column mapping is enabled |
Clone ID column column_map.clone_id | — | text | — | N/A (wrapper-specific) | Shown when Enable input column mapping is enabled |
Aligned sequence column column_map.sequence_alignment | — | text | — | N/A (wrapper-specific) | Shown when Enable input column mapping is enabled |
Germline alignment column column_map.germline_alignment_d_mask | — | text | — | N/A (wrapper-specific) | Shown when Enable input column mapping is enabled |
V call column column_map.v_call | — | text | — | N/A (wrapper-specific) | Shown when Enable input column mapping is enabled |
J call column column_map.j_call | — | text | — | N/A (wrapper-specific) | Shown when Enable input column mapping is enabled |
Junction length column column_map.junction_length | — | text | — | N/A (wrapper-specific) | Shown when Enable input column mapping is enabled |
Junction column (optional if junction_length mapped) column_map.junction | — | text | — | N/A (wrapper-specific) | Shown when Enable input column mapping is enabled |
Cell ID column (paired H/L) column_map.cell_id | — | text | — | N/A (wrapper-specific) | Shown when Enable input column mapping is enabled and Chain mode = HL |
Locus column (paired H/L) column_map.locus | — | text | — | N/A (wrapper-specific) | Shown when Enable input column mapping is enabled and Chain mode = HL |
V region start column column_map.v_region_start | — | text | — | N/A (wrapper-specific) | Shown when Enable input column mapping is enabled and Use region columns (formatClones) is enabled |
V region end column column_map.v_region_end | — | text | — | N/A (wrapper-specific) | Shown when Enable input column mapping is enabled and Use region columns (formatClones) is enabled |
J region start column column_map.j_region_start | — | text | — | N/A (wrapper-specific) | Shown when Enable input column mapping is enabled and Use region columns (formatClones) is enabled |
J region end column column_map.j_region_end | — | text | — | N/A (wrapper-specific) | Shown when Enable input column mapping is enabled and Use region columns (formatClones) is enabled |
Tree Construction
| Field | What it is / used for | Allowed values | Default | Maps to method parameter | Visible when |
|---|---|---|---|---|---|
Analysis mode analysis_mode | — | tree_only, tree_with_internal_sequences, discrete_trait_analysis, time_evolution | tree_only | — | Always |
Tree build method tree_buildRequired | — | pratchet, pml, dnapars, dnaml, igphyml, raxml | pratchet | Selects Dowser's tree-building algorithm — the enum values are Dowser's own build options (pratchet, pml, dnapars, dnaml, igphyml, raxml). | Always |
Min seq/clone minseq | — | integer | 3 | Dowser formatClones minimum sequences per clone. | Always |
Threads nproc | — | integer | 1 | — | Always |
Random seed seed | Seed for stochastic tree search (e.g. the pratchet parsimony ratchet). Fixing this makes a run reproducible: the same input, parameters and seed produce the same tree. Also forwarded as rseed to RAxML-NG / IgPhyML builders, which ignore R's RNG. | integer (≥ 0) | 42 | — | Always |
Collapse identical sequences collapse_identical_sequences | — | Yes / No | Yes | Dowser formatClones collapse-identical-sequences option. | Always |
Trait columns to preserve (advanced) trait_fields | Optional comma- or space-separated columns passed to Dowser formatClones as traits, so identical sequences with different trait values are not collapsed together. In DTA mode, leave empty to use Trait field (DTA). | text | — | Passed to Dowser formatClones as traits. | Always |
Pad to codon length (formatClones) mod3 | When true, Dowser formatClones pads sequence ends to make lengths multiples of three. Default false in this framework to avoid changing sequence lengths unless requested. | Yes / No | No | Dowser formatClones mod3 (pad sequence lengths to multiples of three). | Always |
Remove stop-codon sequences (formatClones) filterstop | When true, Dowser formatClones removes sequences with in-frame stop codons. Default false in this framework to avoid silent sequence removal. | Yes / No | No | Dowser formatClones filterstop (drop sequences with in-frame stop codons). | Always |
Use region columns (formatClones) use_regions | When true, Dowser formatClones assigns CDR/FWR regions. Requires region start/end columns in the input. | Yes / No | No | Dowser formatClones region assignment (uses CDR/FWR region columns). | Always |
Collapse internal nodes collapse_internal_nodes | — | Yes / No | Yes | — | Always |
Check divergence check_divergence | — | Yes / No | Yes | — | Always |
Output & Plotting
| Field | What it is / used for | Allowed values | Default | Maps to method parameter | Visible when |
|---|---|---|---|---|---|
Tip label column (display only) label_field | Display labels only; canonical Newick always uses sequence_id. | text | sequence_id | — | Always |
Color tips by (column) tip_color_by | — | text | — | — | Always |
Unknown fill (plotting only) unknown_value | — | text | unknown | — | Always |
Extra annotation columns annotation_fields | — | text | — | — | Always |
Numeric annotation columns numeric_annotation_fields | — | text | — | — | Always |
Additional columns to retain columns | — | text | — | — | Always |
Tip size (constant) tipsize | — | number | 2 | — | Always |
Scale tip size by (column) tip_size_by | Numeric metadata column for variable tip sizes in Method Output PNG (e.g. duplicate_count). Overrides constant tipsize when the column is present after formatClones. | text | — | — | Always |
Max tip categories max_tip_categories | — | integer | 30 | — | Always |
Internal Sequences
| Field | What it is / used for | Allowed values | Default | Maps to method parameter | Visible when |
|---|---|---|---|---|---|
Return internal sequences return_internal_sequences | — | Yes / No | No | — | Shown when Analysis mode = tree_with_internal_sequences or Analysis mode = tree_only or Analysis mode = discrete_trait_analysis |
Show node numbers in plot show_node_numbers | — | Yes / No | No | — | Shown when Return internal sequences is enabled or Analysis mode = tree_with_internal_sequences |
Export all sequences FASTA export_all_sequences_fasta | — | Yes / No | No | — | Shown when Return internal sequences is enabled |
Discrete Trait Analysis
| Field | What it is / used for | Allowed values | Default | Maps to method parameter | Visible when |
|---|---|---|---|---|---|
Trait field (DTA) trait_field | — | text | — | — | Shown when Analysis mode = discrete_trait_analysis |
Trait model trait_model | — | unconstrained, isotype_irreversible | unconstrained | — | Shown when Analysis mode = discrete_trait_analysis |
Custom trait model file modelfile | Paste Dowser parsimony model-file content. | text | — | Custom Dowser parsimony trait model-file content. | Shown when Analysis mode = discrete_trait_analysis |
DTA permutations permutations | — | integer | 100 | — | Shown when Analysis mode = discrete_trait_analysis |
Tip switch threshold tip_switch | — | integer | 20 | — | Shown when Analysis mode = discrete_trait_analysis |
Permute all permute_all | — | Yes / No | No | — | Shown when Analysis mode = discrete_trait_analysis |
SP test alternative alternative | — | greater, less, two.sided | greater | — | Shown when Analysis mode = discrete_trait_analysis |
Run testPS run_test_ps | — | Yes / No | Yes | Runs Dowser testPS (parsimony-score association test). | Shown when Analysis mode = discrete_trait_analysis |
Run testSP run_test_sp | — | Yes / No | Yes | Runs Dowser testSP (switch-proportion test). | Shown when Analysis mode = discrete_trait_analysis |
Run testSC run_test_sc | — | Yes / No | Yes | Runs Dowser testSC (switch-count test). | Shown when Analysis mode = discrete_trait_analysis |
Isotype order (CSR) isotype_order | — | text | — | — | Shown when Analysis mode = discrete_trait_analysis and Trait model = isotype_irreversible |
Isotype exceptions isotype_exceptions | — | text | IGHD,IGHM | — | Shown when Analysis mode = discrete_trait_analysis and Trait model = isotype_irreversible |
IgPhyML
| Field | What it is / used for | Allowed values | Default | Maps to method parameter | Visible when |
|---|---|---|---|---|---|
IgPhyML partition model partition_model | — | single, cf, hl, hlf, hlc, hlcf | single | IgPhyML partition model (single, cf, hl, hlf, hlc, hlcf). | Shown when Tree build method = igphyml |
Return IgPhyML parameters return_igphyml_parameters | — | Yes / No | Yes | — | Shown when Tree build method = igphyml |
Paired H/L Chains
| Field | What it is / used for | Allowed values | Default | Maps to method parameter | Visible when |
|---|---|---|---|---|---|
Chain mode chain_mode | — | H, HL | H | — | Always |
Heavy locus heavy_locus | — | text | IGH | — | Shown when Chain mode = HL |
Split light chains split_light | — | Yes / No | No | — | Shown when Chain mode = HL |
Light chain traits light_traits | — | Yes / No | No | — | Shown when Chain mode = HL |
Major light chain only majoronly | — | Yes / No | No | — | Shown when Chain mode = HL |
Time Evolution
| Field | What it is / used for | Allowed values | Default | Maps to method parameter | Visible when |
|---|---|---|---|---|---|
Time field time_field | — | text | — | — | Shown when Analysis mode = time_evolution |
Time evolution permutations time_permutations | — | integer | 100 | — | Shown when Analysis mode = time_evolution |
Parse time as numeric time_as_numeric | — | Yes / No | Yes | — | Shown when Analysis mode = time_evolution |
Conditional fields & behaviour
Fields that appear or change based on other inputs
- Raw FASTA is not accepted — Dowser expects sequences already processed through AIRR / Change-O / IgBLAST / IMGT.
- The Discrete Trait Analysis fields appear only in that analysis mode; the IgPhyML partition options appear only when the tree builder is IgPhyML; the paired heavy/light options appear only in HL chain mode.