From 3b353870e7128145ab993e91a94f2fe34b119783 Mon Sep 17 00:00:00 2001
From: PaulinaMartin96 <paulinamartin96@ciencias.unam.mx>
Date: Thu, 29 Aug 2024 02:09:32 -0600
Subject: [PATCH] Add documentation and docstrings for ridgeline, forest and
 caterpilar plots (#328)

* Add documentation and docstrings for ridgeline, forest and caterpilar plots

* Update docs/src/statsplots.md

---------

Co-authored-by: Hong Ge <3279477+yebai@users.noreply.github.com>
---
 docs/src/index.md      | 11 ++++++
 docs/src/statsplots.md | 78 +++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 88 insertions(+), 1 deletion(-)

diff --git a/docs/src/index.md b/docs/src/index.md
index 00ee0ad9..4a8fa1e1 100644
--- a/docs/src/index.md
+++ b/docs/src/index.md
@@ -2,3 +2,14 @@
 
 Implementation of Julia types for summarizing MCMC simulations and utility functions for [diagnostics](@ref Diagnostics) and [visualizations](@ref StatsPlots.jl).
 
+```@docs
+ridgelineplot(chains::Chains, par_names::Vector{Symbol}; hpd_val = [0.05, 0.2],
+q = [0.1, 0.9], spacer = 0.5, _riser = 0.2, show_mean = true, show_median = true,
+show_qi = false, show_hpdi = true, fill_q = true, fill_hpd = false, ordered = false)
+```
+
+```@docs
+forestplot(chains::Chains, par_names::Vector{Symbol}; hpd_val = [0.05, 0.2], q = [0.1, 0.9],
+spacer = 0.5, _riser = 0.2, show_mean = true, show_median = true, show_qi = false,
+show_hpdi = true, fill_q = true, fill_hpd = false, ordered = false)
+```
diff --git a/docs/src/statsplots.md b/docs/src/statsplots.md
index c0482652..41e7339f 100644
--- a/docs/src/statsplots.md
+++ b/docs/src/statsplots.md
@@ -2,7 +2,7 @@
 
 MCMCChains implements many functions for plotting via [StatsPlots.jl](https://github.com/JuliaPlots/StatsPlots.jl).
 
-## Simple example 
+## Simple example
 
 The following simple example illustrates how to use Chain to visually summarize a MCMC simulation:
 
@@ -90,3 +90,79 @@ autocorplot(chn)
 ```@example statsplots
 corner(chn)
 ```
+
+For plotting multiple parameters, Ridgeline, Forest and Caterpillar plots can be useful.
+Please see the docstrings for a detailed description of these functions.
+
+## Ridgeline
+
+```@example statsplots
+ridgelineplot(chn, [:C, :B, :A])
+```
+""""
+    ridgelineplot(chains::Chains, par_names::Vector{Symbol}; hpd_val = [0.05, 0.2],
+    q = [0.1, 0.9], spacer = 0.5, _riser = 0.2, show_mean = true, show_median = true,
+    show_qi = false, show_hpdi = true, fill_q = true, fill_hpd = false, ordered = false)
+
+Given a `chains` object, returns a Ridgeline plot for the sampled parameters specified on
+`par_names`.
+
+For ridgeline plots, the following parameters are defined:
+
+** (a) Fill **
+Fill area below the curve can be determined by quantiles interval (`fill_q = true`) or
+hdpi interval (`fill_hpd = true`). Default options are `fill_hpd = true` and `fill_q = false`.
+If both `fill_q = false` and `fill_hpd = false`, then the whole area below the curve will be
+filled. If no fill color is desired, it should be specified with series attributes. These
+fill options are mutually exclusive.
+
+** (b) Mean and median **
+A vertical line can be plotted repesenting the mean (`show_mean = true`) or median
+(`show_median = true`) of the density (kde) distribution. Both options can be plotted at the
+ same time.
+
+** (c) Intervals **
+At the bottom of each density plot, a quantile interval (`show_qi = true`) or HPD interval
+(`show_hdpi = true`) can be plotted. These options are mutually exclusive. Default options
+are `show_qi = false` and `show_hpdi = true`.To plot quantile intervals, the values specified
+as `q` will be taken, and for HPD intervals, only the smaller value specified in `hpd_val`
+will be used.
+
+Note: When one parameter is given, it will be plotted as a density plot with all the elements
+described above.
+"""
+
+## Forest
+
+```@example statsplots
+forestplot(chn, [:C, :B, :A], hpd_val = [0.05, 0.15, 0.25])
+```
+
+"""
+    forestplot(chains::Chains, par_names::Vector{Symbol}; hpd_val = [0.05, 0.2],
+    q = [0.1, 0.9], spacer = 0.5, _riser = 0.2, show_mean = true, show_median = true,
+    show_qi = false, show_hpdi = true, fill_q = true, fill_hpd = false, ordered = false)
+
+Given a `chains` object, returns a Forest plot for the sampled parameters specified on
+`par_names`.
+
+Both `forest` and `caterpillar` plots are called using `forestplot` shorthands.
+If `ordered = false`, then a `forest` plot will be returned, and if `ordered = true`,
+a `caterpillar` plot will be returned.
+
+For both plot types the following elemets can be plotted:
+
+**High posterior density intervals (HPDI)** determined by the number of elements in `hpd_val`.
+All the values in `hpd_val` will be used to construct the intervals with `MCMCChains.hpd.
+
+**Quantile intervals** determined by the 2-element vector `q`.
+
+**Mean and/or median.** Plotted as points with different `markershape..
+
+"""
+
+## Caterpillar
+
+```@example statsplots
+forestplot(chn, chn.name_map[:parameters], hpd_val = [0.05, 0.15, 0.25], ordered = true)
+```