---
title: "04 Credible intervals for transition probabilities: Cypripedium calceolus"
author: "Raymond Tremblay"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{04 Credible intervals for transition probabilities: Cypripedium calceolus}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---
```{r setup, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment  = "#>",
  fig.width  = 7,
  fig.height = 5
)
```

## Introduction

This vignette demonstrates how to use `transition_CrI()` and
`plot_transition_CrI()` to compute and visualise Bayesian credible intervals
for transition probabilities, and how the choice of prior weight influences
the posterior estimates.

We use a published transition matrix for the lady's slipper orchid
*Cypripedium calceolus*, a long-lived, clonal species of conservation concern
in Europe. The matrix was extracted from the COMPADRE Plant Matrix Database
(MatrixID 242623; Salguero-Gómez et al. 2015), originally published in
Shefferson et al. (2001, *Conservation Biology*,
DOI: 10.1111/j.1523-1739.2010.01466.x).

We use **matU** — the survival-and-growth sub-matrix — which contains only
transitions between living stages. This is the appropriate input for
`raretrans`, which models transition probabilities using a
Dirichlet-multinomial model.

## The *Cypripedium calceolus* transition matrix (matU)

The population is structured into six stages:
**Dormant**, **Smallest**, **Small**, **Intermediate**, **Large**, and
**Extra Large**.
```{r data}
library(raretrans)

stage_names <- c("Dormant", "Smallest", "Small",
                 "Intermediate", "Large", "Extra Large")

# matU: survival and growth transitions only (matA = matU + matF + matC)
# Source: COMPADRE MatrixID 242623
# Shefferson et al. (2001) Conservation Biology
# DOI: 10.1111/j.1523-1739.2010.01466.x
matU <- matrix(
  c(0.78, 0.00, 0.00, 0.00, 0.00, 0.00,
    0.06, 0.42, 0.03, 0.00, 0.00, 0.00,
    0.00, 0.24, 0.62, 0.05, 0.00, 0.00,
    0.00, 0.00, 0.21, 0.73, 0.06, 0.00,
    0.00, 0.00, 0.00, 0.12, 0.74, 0.07,
    0.00, 0.00, 0.00, 0.00, 0.11, 0.83),
  nrow = 6, ncol = 6, byrow = TRUE,
  dimnames = list(stage_names, stage_names)
)

# Construct TF list (no fecundity in matU so F is all zeros)
F_mat <- matrix(0, nrow = 6, ncol = 6,
                dimnames = list(stage_names, stage_names))
TF <- list(T = matU, F = F_mat)

# Observed stage distribution (number of individuals per stage)
N <- c(15, 12, 28, 34, 22, 10)
names(N) <- stage_names

matU
```

Note that the columns of `matU` do not sum to 1 — the remainder represents
individuals that died during the census interval and is handled internally
by `raretrans` as the implicit "dead" fate.

## Computing credible intervals

`transition_CrI()` computes the marginal posterior beta credible interval
for every entry of the transition matrix, including the probability of dying.
By default it uses a uniform (uninformative) Dirichlet prior.
```{r cri_default}
cri_uniform <- transition_CrI(TF, N, stage_names = stage_names)
head(cri_uniform, 10)
```

Each row gives the posterior **mean** transition probability and its
**lower** and **upper** 95% credible interval bounds.

## Visualising with `plot_transition_CrI()`

### Including the dead fate (default)
```{r plot_with_dead, fig.cap = "Posterior transition probabilities with 95% credible intervals for all fates including mortality."}
plot_transition_CrI(cri_uniform,
                    title = "Cypripedium calceolus — uniform prior")
```

Each panel shows the fate distribution from one source stage. Points are
posterior means; vertical bars are 95% credible intervals. Wide intervals
indicate stages with few observed individuals.

### Excluding the dead fate
```{r plot_no_dead, fig.cap = "Posterior transition probabilities excluding the dead fate."}
plot_transition_CrI(cri_uniform,
                    include_dead = FALSE,
                    title = "Cypripedium calceolus — transitions only")
```

Excluding the dead fate focuses attention on survival transitions between
living stages, which is often more informative for life-history comparisons.

## Effect of prior weight

The `priorweight` argument controls how much the prior pulls estimates
toward equal probabilities. A value of `-1` (the default) uses a
minimally informative prior. Positive values express the prior weight as
a percentage of the observed sample size — for example, `priorweight = 50`
means the prior contributes half as many pseudo-observations as the data.

This matters most for rare stages with few observed individuals, where the
prior can have a strong regularising effect.
```{r prior_comparison}
# Uninformative prior (default)
cri_uninf <- transition_CrI(TF, N,
                             priorweight  = -1,
                             stage_names  = stage_names)

# Weakly informative prior (25% of sample size)
cri_weak  <- transition_CrI(TF, N,
                             priorweight  = 25,
                             stage_names  = stage_names)

# Strongly informative prior (100% of sample size)
cri_strong <- transition_CrI(TF, N,
                              priorweight = 100,
                              stage_names = stage_names)

# Compare interval widths for the Dormant stage
comp <- data.frame(
  prior      = c("Uninformative", "Weak (25%)", "Strong (100%)"),
  mean_width = c(
    mean(cri_uninf[cri_uninf$from_stage  == "Dormant", "upper"] -
         cri_uninf[cri_uninf$from_stage  == "Dormant", "lower"]),
    mean(cri_weak[cri_weak$from_stage    == "Dormant", "upper"] -
         cri_weak[cri_weak$from_stage    == "Dormant", "lower"]),
    mean(cri_strong[cri_strong$from_stage == "Dormant", "upper"] -
         cri_strong[cri_strong$from_stage == "Dormant", "lower"])
  )
)
comp
```
```{r plot_prior_comparison, fig.height = 10, fig.cap = "Effect of prior weight on credible interval width. Stronger priors narrow the intervals and pull means toward equal transition probabilities."}
library(ggplot2)

cri_uninf$prior  <- "Uninformative"
cri_weak$prior   <- "Weak (25%)"
cri_strong$prior <- "Strong (100%)"

cri_all <- rbind(cri_uninf, cri_weak, cri_strong)
cri_all$prior <- factor(cri_all$prior,
                        levels = c("Uninformative",
                                   "Weak (25%)",
                                   "Strong (100%)"))

ggplot(cri_all,
       aes(x = to_stage, y = mean, ymin = lower, ymax = upper,
           colour = prior)) +
  geom_pointrange(position = position_dodge(width = 0.5)) +
  facet_wrap(~from_stage, scales = "free_x") +
  scale_y_continuous(limits = c(0, 1)) +
  scale_colour_manual(values = c("Uninformative" = "grey40",
                                 "Weak (25%)"    = "steelblue",
                                 "Strong (100%)" = "firebrick")) +
  labs(x      = "Destination stage",
       y      = "Transition probability",
       colour = "Prior weight",
       title  = "Effect of prior weight on credible intervals",
       subtitle = "Cypripedium calceolus — matU") +
  theme_bw() +
  theme(axis.text.x = element_text(angle = 45, hjust = 1))
```

A stronger prior (red) shrinks credible intervals and pulls posterior means
toward equal probabilities. For well-sampled stages (e.g. Intermediate,
Large) the effect is small. For rare stages (e.g. Dormant, Extra Large)
the prior has a more pronounced influence — a good reason to think
carefully about prior choice when sample sizes are small.

## Visualising full posterior densities

`plot_transition_density()` shows the complete marginal posterior beta
distribution for every transition, arranged as an (n+1) x n grid mirroring
the structure of the projection matrix. Columns are source stages (from) and
rows are destination stages (to), with the dead fate as the bottom row.
The shaded region shows the 95% credible interval.

### With uninformative prior

```{r density_uninf, fig.width = 9, fig.height = 8, fig.cap = "Full posterior beta densities for all transitions with uninformative prior. Shaded region = 95% credible interval."}
plot_transition_density(TF, N,
                        stage_names  = stage_names,
                        title        = "Cypripedium calceolus — uninformative prior")
```

Wide, flat densities indicate high uncertainty (few observations).
Narrow, peaked densities indicate well-estimated transitions.
Panels where the probability is near zero show a density spike at 0 —
this is expected behaviour for impossible transitions.

### Effect of prior weight on densities

A stronger prior pulls densities toward the centre and narrows them,
particularly for rare stages.

```{r density_strong, fig.width = 9, fig.height = 8, fig.cap = "Posterior beta densities with a strong prior (100% of sample size)."}
plot_transition_density(TF, N,
                        priorweight  = 100,
                        stage_names  = stage_names,
                        title        = "Cypripedium calceolus — strong prior (100%)")
```

### Excluding the dead fate

```{r density_no_dead, fig.width = 9, fig.height = 7, fig.cap = "Posterior densities for survival transitions only (dead fate excluded)."}
plot_transition_density(TF, N,
                        stage_names  = stage_names,
                        include_dead = FALSE,
                        title        = "Cypripedium calceolus — transitions only")
```

## Summary

| Function | Purpose |
|---|---|
| `transition_CrI()` | Compute posterior beta credible intervals for all transitions |
| `plot_transition_CrI()` | Point-range plot of means and CIs, one panel per source stage |
| `plot_transition_density()` | Full posterior density curves arranged as a matrix plot |

For the full posterior density visualisation see `?plot_transition_density`.

## References



Salguero-Gómez, R., Jones, O.R., Archer, C.R., et al. (2015).
The COMPADRE Plant Matrix Database: an open online repository for plant
demography. *Journal of Ecology*, 103, 202–218.

