---
title: "Creating your first ggrank plot"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Creating your first ggrank plot}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(collapse = TRUE, comment = "#>", fig.width = 10, fig.height = 6)
```

`ggrank` shows how categories move through an ordered ranking while retaining
their underlying values. Start with one row per category and period and map the
three required columns.

> **Teaching-data notice:** All datasets bundled with `ggrank` are synthetic.
> They do not contain Global Burden of Disease estimates. `ggrank` is an
> independent project and is not affiliated with or endorsed by the Institute
> for Health Metrics and Evaluation (IHME).

```{r}
library(ggrank)

ggrank(
  ggrank_products,
  category = product,
  period = year,
  value = sales,
  periods = c(2022, 2024),
  top_n = 5,
  value_header = "Sales"
)
```

The boundary view is the default: a category outside the top five remains in
the figure when it enters or exits the top five in another displayed period.

## Let ggrank calculate the ranks

Users normally supply values rather than ranks. Inspect the calculation with
`ggrank_data()`:

```{r}
tied_rates <- data.frame(
  year = rep(c(2020, 2025), each = 5),
  organism = rep(c("A", "B", "C", "D", "E"), 2),
  rate = c(5, 4, 3, 3, 2, 6, 4, 4, 2, 1)
)

ggrank_data(
  tied_rates,
  category = organism,
  period = year,
  value = rate
)
```

Ranking uses exact numeric values. Equal values share a competition rank by
default (`1, 2, 3, 3, 5`) but receive separate alphabetical display positions.
All categories tied at the `top_n` boundary are included, so a top-ten figure
can contain more than ten boxes. Do not filter to the top N before calling the
package, because doing so prevents entrant and exit detection.

Display formatting is independent of ranking. For example, rank an unrounded
rate while printing a prepared one-decimal label:

```{r}
formatted_rates <- transform(
  tied_rates,
  rate_label = sprintf("%.1f per 100,000", rate)
)

ggrank(
  formatted_rates,
  category = organism,
  period = year,
  value = rate,
  label = rate_label
)
```

## Use existing ranks without marks or values

If a school, institution, or report already supplies authoritative ranks, no
mark, rate, score, or other value column is needed.

```{r}
student_ranks <- data.frame(
  year = rep(c(2024, 2025), each = 4),
  student = rep(c("Asha", "Ben", "Chen", "Dina"), 2),
  institution = "North School",
  rank = c(1, 2, 3, 4, 3, 1, 2, 4)
)

ggrank(
  student_ranks,
  category = student,
  period = year,
  rank = rank,
  group = institution,
  top_n = 4
)
```

The rank-only layout omits the value boxes. The same input works with
`ggrank_data()`, `ggrank_table()`, and `ggrank_change()`. Ranks must be finite,
positive whole numbers. `group` changes colours; it does not calculate ranks
separately for each group. Separate institutional ranking lists should be
analysed separately or represented by distinct period/list identifiers.

## Group colours and prepared labels

Use `group` for meaningful category colours and `label` when values require a
domain-specific display format. Supplied ranks are also supported.

```{r}
ggrank(
  ggrank_causes,
  category = cause,
  period = year,
  value = rate,
  rank = rank,
  label = display_value,
  group = cause_group,
  periods = c(1990, 2021),
  top_n = 10,
  value_header = "Rate (95% interval)"
)
```

The returned value is a regular ggplot object, so titles, captions, and other
ggplot2 layers can be added normally.

## Inspect the underlying comparison

`ggrank_table()` returns a readable analytical companion with one row per
category and adjacent transition.

```{r}
changes <- ggrank_table(
  ggrank_products,
  category = product,
  period = year,
  value = sales,
  periods = c(2022, 2024),
  top_n = 5
)

changes
```

Visualise the largest rises and falls directly from that table. Positive
values moved towards rank one; negative values moved away from rank one.

```{r}
ggrank_change(changes, top = 5)
```

## Use the graphical interface

Launch the optional local Shiny interface when you prefer to choose columns
and settings interactively:

```{r, eval=FALSE}
ggrank_app()
```

Start with either synthetic teaching dataset or upload a CSV. The GUI presents
the rank chart, change chart, analytical table, and calculated rank data in
separate tabs. Close the Shiny window or stop the R process to return to the
console.