Issue #82: Link between vignettes

NEWS.md

@@ -10,6 +10,7 @@ This is the development version of `primarycensoreddist` and is not yet ready fo
 ## Documentation
 
 * Simplified the "Analytic solutions" vignette by removing verbose derivation details.
+* Added links between vignettes to make it easier to navigate the documentation.
 
 # primarycensoreddist 0.5.0
 

vignettes/analytic-solutions.Rmd

@@ -16,6 +16,15 @@ vignette: >
   %\VignetteEncoding{UTF-8}
 ---
 
+# What are we going to do in this Vignette
+
+In this vignette, we'll derive the analytic solutions for the primary censored delay distributions for a range of commonly used distributions.
+
+1. Examine the case of exponentially tilted primary event times
+2. Analyse the uniform primary event time case ($r=0$)
+3. Explore general partial expectation and its role in solving equation \@ref(eq:unifprim)
+4. Provide specific analytic solutions for distributions where the partial expectation can be reduced to an analytic expression
+
 
 # Analytic solutions for exponentially tilted primary event times
 
@@ -32,7 +41,7 @@ F_{C_P}(p; r) = {  1 - \exp(-r p) \over 1 - \exp(-r w_P)}, \qquad p \in [0, w_P]
 $$
 Note that taking the limit $\lim_r \rightarrow 0$ in equation \@ref(eq:fcp) gives the uniform distribution function $F_{C_P}(p, 0) = p / w_P$.
 
-In the following it is convenient to use a (linear) difference operator defined as:
+In the following, it is convenient to use a (linear) difference operator defined as:
 
 $$
 \Delta_{w}f(t) = f(t + w) - f(t).
@@ -57,7 +66,7 @@ Q_{S_+}(t) &= Q_T(t + w_P) + { 1 \over w_P} \int_t^{t+w_P} f_T(z) (z-t)~ dz \\
 \end{aligned} (\#eq:unifprim)
 $$
 
-**General partial expectation**
+## General partial expectation
 
 Note that for any distribution with an analytically available distribution function $F_T$ equation \@ref(eq:unifprim) can be solved so long as the _partial expectation_
 
@@ -69,7 +78,7 @@ can be reduced to an analytic expression.
 
 The insight here is that this will be possible for any distribution where the average of the distribution can be calculated analytically, which includes commonly used non-negative distributions such as the Gamma, Log-Normal and Weibull distributions.
 
-**General Discrete censored delay distribution**
+## General Discrete censored delay distribution
 
 First, we note that equation 3.3 from ["Why it works"](why-it-works.html) can be written using the difference operator: $f_n = -\Delta_1 Q_{S_+}(n-1)$. We can insert this expression into equation \@ref(eq:unifprim) to give the discrete censored delay distribution for uniformly distributed primary event times:
 
@@ -101,7 +110,7 @@ F_T(z;k, \theta) &= 0, \qquad z < 0.
 $$
 Where $\gamma$ is the lower incomplete gamma function.
 
-**Gamma partial expectation**
+### Gamma partial expectation
 
 We know that the full expectation of the Gamma distribution is $\mathbb{E}[T] = k\theta$, which can be calculated as a standard integral. Doing the same integral for the partial expectation gives:
 
@@ -113,7 +122,7 @@ $$
 \end{aligned} (\#eq:gammapartexp)
 $$
 
-**Survival function of $S_{+}$ for Gamma distribution**
+### Survival function of $S_{+}$ for Gamma distribution
 
 By substituting equation \@ref(eq:gammapartexp) into equation \@ref(eq:disccensunifprim) we can solve for the survival function of $S_+$ in terms of analytically available functions:
 
@@ -122,7 +131,7 @@ Q_{S_+}(t; k, \theta) = Q_T(t + w_P; k, \theta) + { 1 \over w_P} \big[ k \theta
 (\#eq:survgammaunifprim)
 $$
 
-**Gamma discrete censored delay distribution**
+### Gamma discrete censored delay distribution
 
 By substituting \@ref(eq:survgammaunifprim) into \@ref(eq:disccensunifprim) we get the discrete censored delay distribution in terms of analytically available functions:
 $$
@@ -149,7 +158,7 @@ F_T(z;\mu, \sigma) = \Phi\left( {\log(z) - \mu \over \sigma} \right).
 $$
 Where $\Phi$ is the standard normal distribution function.
 
-**Log-Normal partial expectation**
+### Log-Normal partial expectation
 
 We know that the full expectation of the Log-Normal distribution is $\mathbb{E}[T] = e^{\mu + \frac{1}{2} \sigma^2}$, which can be calculated by integration with the integration substitution $y = (\ln z - \mu) / \sigma$. This has transformation Jacobian:
 
@@ -169,15 +178,15 @@ $$
 \end{aligned} (\#eq:lognormpartexp)
 $$
 
-**Survival function of $S_{+}$ for Log-Normal distribution**
+### Survival function of $S_{+}$ for Log-Normal distribution
 
 By substituting equation \@ref(eq:lognormpartexp) into equation \@ref(eq:disccensunifprim) we can solve for the survival function of $S_+$ in terms of analytically available functions:
 
 $$
 Q_{S+}(t ;\mu, \sigma) = Q_T(t + w_P;\mu, \sigma) + { 1 \over w_P} \Big[ e^{\mu + \frac{1}{2} \sigma^2} \Delta_{w_P}F_T(t; \mu + \sigma^2, \sigma) - t\Delta_{w_P}F_T(t; \mu, \sigma) \Big]
 $$
 
-**Log-Normal discrete censored delay distribution**
+### Log-Normal discrete censored delay distribution
 
 By substituting \@ref(eq:lognormpartexp) into \@ref(eq:disccensunifprim) we get the discrete censored delay distribution in terms of analytically available functions:
 
@@ -208,7 +217,7 @@ F_T(z;\lambda,k))=\begin{cases}1 - e^{-(z/\lambda)^k}, & z\geq0,\\ 0, & z<0.\end
 $$
 Where $\Phi$ is the standard normal distribution function.
 
-**Weibull partial expectation**
+### Weibull partial expectation
 
 We know that the full expectation of the Weibull distribution is $\mathbb{E}[T] = \lambda \Gamma(1 + 1/k)$, which can be calculated by integration using the integration substitution $y = (z / \lambda)^k$, which has transformation Jacobian:
 
@@ -235,15 +244,15 @@ g(t; \lambda, k) = \gamma(1 + 1/k, (t/\lambda)^k) = \frac{1}{k}\gamma(1/k, (t/\l
 $$
 is a reparametrisation of the lower incomplete gamma function.
 
-**Survival function of $S_{+}$ for Weibull distribution**
+## Survival function of $S_{+}$ for Weibull distribution
 
 By substituting equation \@ref(eq:weibullpartexp) into equation \@ref(eq:disccensunifprim) we can solve for the survival function of $S_+$ in terms of analytically available functions:
 
 $$
 Q_{S+}(t ;\lambda,k) = Q_T(t + w_P; \lambda,k) + { 1 \over w_P} \Big[ \lambda \Delta_{w_P} g(t; \lambda,k) - t\Delta_{w_P}F_T(t; \lambda,k)\Big].
 $$
 
-**Weibull discrete censored delay distribution**
+### Weibull discrete censored delay distribution
 
 By substituting \@ref(eq:weibullpartexp) into \@ref(eq:disccensunifprim) we get the discrete censored delay distribution in terms of analytically available functions:
 
@@ -257,4 +266,10 @@ f_n &= (n+1)F_T(n+1)  + (n-1)F_T(n-1) - 2nF_T(n) - \Delta_1\Big[ \int_{n-1}^n f_
 $$
 
 Which was also found by Cori _et al_ [@cori2013new].
+
+# Learning more
+
+- For more mathematical background on the analytic solutions see the `vignette("why-it-works")`.
+- For a more introductory explanation of the primary event censored distribution see the `vignette("primarycensoreddist")`.
+
 # References

vignettes/primarycensoreddist.Rmd

@@ -286,5 +286,7 @@ In addition to these main functions, the package also includes:
 # Learning more
 
 - For more on `primarycensoreddist` see the other package vignettes and the function documentation.
+- For a more detailed explanation of the mathematical formulation of the primary event censored distribution see the `vignette("why-it-works")`.
+- For more mathematical details on the analytic solutions see the `vignette("analytic-solutions")`.
 - For more methodological background on delay distributions see Park et al.[@Park2024].
 - For advice on best practices when estimating or handling delay distributions see Charniga et al.[@Charniga2024].

vignettes/why-it-works.Rmd

@@ -27,6 +27,7 @@ In this vignette, we'll explain the underlying statistical model that the `prima
 3. Introduce the statistical model used in `primarycensoreddist`.
 4. Distributions where we can derive the censored delay distribution analytically.
 
+If you are new to the package, we recommend that you start with the `vignette("primarycensoreddist")` vignette.
 
 # Censoring and right truncation problems in time to event analysis
 
@@ -189,4 +190,9 @@ which is same as equation \@ref(eq:seccensorprob).
 
 In this derivation, we have used that $G_P(x|-w_P, 0)$ is the distribution function from the time _from_ the start of the primary interval _until_ primary event time, and $F_{C_P}$ is the distribution function of the time _until_ the end of the primary event window _from_ the primary event time. Therefore, $G_P(-p|-w_P, 0) = Pr(P < -p | P \in (-w_P, 0)) = 1 - Pr(C_P \leq p) = 1 - F_{C_P}(p)$.
 
+# Learning more
+
+- For more mathematical background on the analytic solutions see the `vignette("analytic-solutions")`.
+- For a more introductory explanation of the primary event censored distribution see the `vignette("primarycensoreddist")`.
+
 # References