Skip to main content

Advanced SSE models

Set state sampling and root treatment, tie BiSSE rates, control the optimizer search, and tune QuaSSE numerics.

The worked example shows why Guane withholds model weights.

  • You’ll learn How to build a constrained BiSSE model, what the optimizer checks mean, and when Guane withholds weights.
  • Time About 35 minutes
  • Prerequisites SSE models tutorial; example loaded and matched in the SSE models Data card
Scientific caution

The bundled example is synthetic. Its values are invented and its branch lengths are arbitrary. Results are a demonstration, not biological evidence.

Before you start

Load the example in the SSE models Data card and click Use matched taxa. Resolve the mismatch shows each step. Each SSE card groups its controls in collapsible sections, such as Model and data settings (open) and Advanced fitting controls.

Sampling and root

Sampling fraction for state 0

The share of living species in state 0 that your tree includes. Sampling fraction for state 1 does the same for state 1.

Where
BiSSE Model and data settings
Default
1 for each state
Change it when
Species in one state are better sampled than in the other. Unequal sampling can mimic state-dependent diversification.
Check after
The model line in Results shows sampling.f.

Root treatment

Sets how the root state is weighted in the likelihood.

Where
BiSSE Model and data settings Root treatment
Default
Observed (ROOT.OBS)
Change it when
You have a justified root prior. Given (ROOT.GIVEN) opens Root probability for state 0.
Check after
The model line in Results shows root. Every candidate in the run uses the same root treatment.

QuaSSE numerics

Measurement-error column

Uses a column of per-species standard errors for the continuous trait.

Where
QuaSSE Model and data settings Measurement-error column
Default
Common standard error, which uses Common measurement standard error (1)
Change it when
You have measured standard errors, in trait units. Zero and missing errors are not supported.
Check after
“The tip grid is coarser than a measurement standard error. Increase resolution; model weights are withheld.”

Trait grid bins

Sets the resolution of the trait grid that QuaSSE integrates over.

Where
QuaSSE Numerical integration controls Trait grid bins
Default
1024
Change it when
The tip grid is coarser than the measurement error, or the likelihood is unstable.
Check after
“Every fit is checked with twice the grid bins and half the time step. Unstable likelihoods suppress model weights.”

Worked recipe

Worked example: a custom BiSSE with tied rates

Start in the BiSSE card, with the example matched in the Data card.

  1. Set Binary trait to habitat_binary. Observed value coded as state 0 defaults to aquatic.
  2. Open Advanced fitting controls and click Fill parameter table.
  3. In BiSSE parameter table (CSV), change the Group of mu1 to mu0 and the Group of q10 to q01. This ties extinction across states and makes transitions symmetric.
  4. Under Models, tick Full, Trait-independent diversification and Custom.
  5. Set Sampling fraction for state 0 and Sampling fraction for state 1 to 0.8 (invented values), and Optimizer starts to 5.
  6. Click Run BiSSE. The status reads “BiSSE completed. Review convergence, bounds and model assumptions.”
  7. Open Diagnostics and check Effective parameter constraints: the Custom model shows the tied groups.

Expect the three models to reach log-likelihoods within a few hundredths of each other, with no weights: “BiSSE ranking weights are unavailable. Inspect individual fits and diagnostics.” Diagnostics warns “A BiSSE rate reached a bound. Inspect bounds and identifiability before interpretation.” and that starts disagree for the Full model. A 19-tip tree cannot separate these models. Its transition rates run to their upper bound, the same pattern as in Advanced ancestral states. If you try Run profile uncertainty on the Full model, Guane refuses: “Resolve fit diagnostics before calculating profile intervals.”

BiSSE advanced fitting controls with a parameter table tying mu1 to mu0 and q10 to q01

The BiSSE parameter table with extinction and transition rates tied.

In the verification table, the Full model’s StartSpread is well above zero, while Verified and Stable are TRUE for all three models. Start disagreement alone is enough to withhold the weights.

BiSSE verification table with columns Model, StartSpread, Verified and Stable: Full has a start spread of about 0.43, Trait-independent diversification and Custom are near zero, and all three are Verified and Stable TRUE

The verification columns: only the Full model’s starts disagree.

BiSSE diagnostics with bound and start-disagreement warnings and the verification table for three models

The full BiSSE diagnostics tab for the three models.

When weights are withheld

Guane shows model weights only when every candidate in the run passes all of these checks:

  • At least two models are selected under Models.
  • It converged, and all of its starts converged.
  • Its likelihood is stable under tighter integration tolerance.
  • The independent optimizer verified it.
  • No rate sits at a bound.
  • Its starts agree, and there were at least two starts.
  • No other candidate found a better feasible point for it.
  • No two candidates have identical constraints.

If any check fails, the weights column stays empty. The failing check is named in Diagnostics.

Before you interpret

Scientific caution
  • A BiSSE preference for trait-dependent rates can come from rate differences unrelated to the trait. Refit in Hidden-state and null models and compare against CID-2 and CID-4.
  • Missing weights mean the models could not be ranked. Do not compute them yourself.
  • Sampling fractions and measurement errors are assumptions you supply. Report them.

Read State-dependent speciation and extinction before you report.