# Raincloud Plot
A raincloud plot (Allen et al. 2019) overlays three complementary views of each group's distribution on a shared axis:
- **Cloud** — a half-violin (KDE) showing the distribution shape
- **Box** — a narrow box-and-whisker showing the five-number summary
- **Rain** — jittered raw points showing every individual observation
This combination avoids the information loss of a box plot (shape is hidden), the visual clutter of a pure strip plot (structure is obscured), and the opacity of a violin (sample size is invisible). All three layers share the same y-axis so they can be compared directly.
**Import path:** `kuva::plot::RaincloudPlot`
---
## Basic usage
Add one group per category with `.with_group(label, values)`. Groups are rendered left-to-right in the order added.
```rust,no_run
use kuva::plot::RaincloudPlot;
use kuva::backend::svg::SvgBackend;
use kuva::render::render::render_multiple;
use kuva::render::layout::Layout;
use kuva::render::plots::Plot;
let plot = RaincloudPlot::new()
.with_group("Control", control_values)
.with_group("Low dose", low_dose_values)
.with_group("High dose", high_dose_values);
let plots = vec![Plot::Raincloud(plot)];
let layout = Layout::auto_from_plots(&plots)
.with_title("Drug response")
.with_x_label("Treatment")
.with_y_label("Response (AU)");
let scene = render_multiple(plots, layout);
let svg = SvgBackend.render_scene(&scene);
std::fs::write("raincloud.svg", svg).unwrap();
```
<img src="../assets/raincloud/basic.svg" alt="Basic raincloud plot" width="560">
By default, multi-group plots use the `category10` palette automatically. For a single group the uniform `.with_color()` value is used.
---
## Toggling elements
Each of the three layers can be turned off independently. This lets you build simpler variants when not all three are needed.
```rust,no_run
# use kuva::plot::RaincloudPlot;
// Cloud + box only (no raw points)
let plot = RaincloudPlot::new()
.with_group("A", data)
.with_rain(false);
// Cloud + rain only (no summary box)
let plot = RaincloudPlot::new()
.with_group("A", data)
.with_box(false);
// Box + rain only (no KDE cloud)
let plot = RaincloudPlot::new()
.with_group("A", data)
.with_cloud(false);
```
---
## KDE bandwidth
The cloud shape is a kernel density estimate. By default, bandwidth is chosen automatically using Silverman's rule-of-thumb, which works well for roughly unimodal, normal-ish data but can over-smooth multimodal distributions.
### Bandwidth scale
`.with_bandwidth_scale(s)` multiplies the auto-computed bandwidth by a factor (equivalent to ggplot2's `adjust`). Values below `1.0` produce a sharper, more data-sensitive curve; values above `1.0` produce a smoother curve.
```rust,no_run
# use kuva::plot::RaincloudPlot;
// Tighter — reveals bimodality or shoulders
let plot = RaincloudPlot::new()
.with_group("A", data)
.with_bandwidth_scale(0.5);
// Wider — emphasises overall shape, less noise
let plot = RaincloudPlot::new()
.with_group("A", data)
.with_bandwidth_scale(2.0);
```
### Explicit bandwidth
`.with_bandwidth(h)` sets an exact bandwidth value, overriding both Silverman's rule and `.with_bandwidth_scale()`.
```rust,no_run
# use kuva::plot::RaincloudPlot;
let plot = RaincloudPlot::new()
.with_group("A", data)
.with_bandwidth(0.4);
```
`.with_kde_samples(n)` controls how many points the KDE is evaluated at (default `200`). The default is adequate for most datasets.
---
## Flip direction
By default the cloud appears to the right of centre and rain to the left. `.with_flip(true)` reverses this.
```rust,no_run
# use kuva::plot::RaincloudPlot;
let plot = RaincloudPlot::new()
.with_group("A", data)
.with_flip(true); // cloud left, rain right
```
<img src="../assets/raincloud/flipped.svg" alt="Flipped raincloud plot" width="560">
---
## Per-group colors
`.with_group_colors()` assigns colors to groups by position.
```rust,no_run
use kuva::plot::RaincloudPlot;
use kuva::backend::svg::SvgBackend;
use kuva::render::render::render_multiple;
use kuva::render::layout::Layout;
use kuva::render::plots::Plot;
let plot = RaincloudPlot::new()
.with_group("Control", control_values)
.with_group("Low dose", low_values)
.with_group("High dose", high_values)
.with_group_colors(["#4878d0", "#ee854a", "#6acc65"]);
let plots = vec![Plot::Raincloud(plot)];
let layout = Layout::auto_from_plots(&plots)
.with_title("Raincloud — per-group colors")
.with_y_label("Response");
let svg = SvgBackend.render_scene(&render_multiple(plots, layout));
```
<img src="../assets/raincloud/group_colors.svg" alt="Raincloud with per-group colors" width="560">
---
## Legend
`.with_legend(label)` triggers per-group legend entries. Each group's label and color appear as a separate row in the legend — the string passed to `.with_legend()` is not used as an entry label but serves as a signal to show the legend.
```rust,no_run
# use kuva::plot::RaincloudPlot;
# use kuva::render::plots::Plot;
# use kuva::render::layout::Layout;
# use kuva::render::render::render_multiple;
# use kuva::backend::svg::SvgBackend;
let plot = RaincloudPlot::new()
.with_group("Control", control_values)
.with_group("Treated", treated_values)
.with_legend("show"); // triggers per-group entries
let plots = vec![Plot::Raincloud(plot)];
let layout = Layout::auto_from_plots(&plots)
.with_title("Treatment comparison");
let svg = SvgBackend.render_scene(&render_multiple(plots, layout));
```
---
## Fine-tuning layout
The offsets and widths of all three elements can be adjusted if groups overlap or look too sparse.
```rust,no_run
# use kuva::plot::RaincloudPlot;
let plot = RaincloudPlot::new()
.with_group("A", data_a)
.with_group("B", data_b)
.with_cloud_width(40.0) // wider cloud (default 30.0 px)
.with_cloud_offset(0.20) // cloud centre further from group centre (default 0.15)
.with_rain_offset(0.25) // rain centre further from group centre (default 0.20)
.with_box_width(0.12) // wider box (default 0.08, fraction of slot)
.with_rain_size(2.5) // smaller rain points (default 3.0 px radius)
.with_rain_jitter(0.04) // tighter horizontal spread (default 0.05)
.with_cloud_alpha(0.6) // slightly more transparent cloud (default 0.7)
.with_rain_alpha(0.5) // more transparent rain (default 0.7)
.with_seed(123); // different jitter seed (default 42)
```
---
## API reference
| `RaincloudPlot::new()` | Create a raincloud plot with defaults |
| `.with_group(label, values)` | Add a group; accepts any `Vec<f64>` |
| `.with_groups(iter)` | Add multiple `(label, values)` pairs at once |
| `.with_color(s)` | Uniform fill color, used for single-group plots (default `"steelblue"`) |
| `.with_group_colors(iter)` | Per-group fill colors matched by position |
| `.with_cloud(bool)` | Show/hide the cloud half-violin (default `true`) |
| `.with_cloud_width(px)` | Maximum pixel half-width of the cloud (default `30.0`) |
| `.with_cloud_offset(f)` | Data-axis offset of cloud centre from group centre (default `0.15`) |
| `.with_cloud_alpha(a)` | Cloud fill opacity 0–1 (default `0.7`) |
| `.with_bandwidth(h)` | Explicit KDE bandwidth; overrides Silverman + scale |
| `.with_bandwidth_scale(s)` | Multiplier on Silverman bandwidth (default `1.0`; `< 1` sharper, `> 1` smoother) |
| `.with_kde_samples(n)` | KDE evaluation points (default `200`) |
| `.with_box(bool)` | Show/hide the box-and-whisker (default `true`) |
| `.with_box_width(f)` | Box half-width as fraction of slot width (default `0.08`) |
| `.with_rain(bool)` | Show/hide the jitter points (default `true`) |
| `.with_rain_size(px)` | Rain point radius in pixels (default `3.0`) |
| `.with_rain_jitter(f)` | Horizontal jitter spread in data units (default `0.05`) |
| `.with_rain_alpha(a)` | Rain point opacity 0–1 (default `0.7`) |
| `.with_rain_offset(f)` | Data-axis offset of rain centre from group centre (default `0.20`) |
| `.with_flip(bool)` | Swap cloud and rain sides (default `false` — cloud right, rain left) |
| `.with_seed(u64)` | RNG seed for reproducible jitter (default `42`) |
| `.with_legend(s)` | Show per-group legend entries |