highdir

<!-- README.md is generated from README.Rmd. Please edit that file -->

# highdir <a href="https://github.com/folkehelsestats/highdir"><img src="man/figures/logo.png" align="right" height="120" alt="highdir website" /></a>

[![R-CMD-check](https://github.com/folkehelsestats/highdir/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/folkehelsestats/highdir/actions/workflows/R-CMD-check.yaml)
[![Codecov test
coverage](https://codecov.io/gh/folkehelsestats/highdir/graph/badge.svg)](https://app.codecov.io/gh/folkehelsestats/highdir)
[![Lifecycle:
experimental](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://lifecycle.r-lib.org/articles/stages.html#experimental)

**highdir** is an R package that provides a unified, backend-agnostic
API for building figures with either
[**highcharter**](https://jkunst.com/highcharter/) (interactive) or
[**ggplot2**](https://ggplot2.tidyverse.org/) (static).

The package provides two complementary yet fully interoperable APIs for
creating figures:

1.  **Declarative API** - define all components of a figure up front and
    render it in a single step.
2.  **Layered API** - incrementally compose a figure by adding layers,
    similar to the *grammar of graphics*.

Both APIs produce equivalent visual output and can target any supported
backend without changes to the calling code.

With the declarative API, a figure is specified once as an `hd_spec`
object and can later be rendered to different backends. Backend-specific
presentation options (such as interactivity or styling tweaks) can be
supplied separately via an `hc_opts` object prior to rendering.

The layered API supports an exploratory, iterative workflow. Figures are
built step by step using `+` similar to **ggplot2** style, making this
approach particularly well suited for interactive analysis and rapid
prototyping, while remaining backend-independent.

By default, **highdir** ships with colour palette, theme, and visual
identity of [The Norwegian Directorate of
Health](https://www.helsedirektoratet.no) (*Helsedirektoratet*). To
further enhance usability, a Shiny graphical user interfacef for
building and previewing figures is also included as part of the package.

------------------------------------------------------------------------

## Installation

``` r
# Install from GitHub
if(!require(remotes)) install.packages("remotes")
remotes::install_github("folkehelsestats/highdir")

# Install from development version (dev branch)
remotes::install_github("folkehelsestats/highdir@dev")
```

------------------------------------------------------------------------

## Get started

The simplest way to get started with *highdir* is by using the built-in
Shiny app. It shows also codes to demonstrate how to use the package
programmatically in R. Start the app with:

``` r
library(highdir)
hd_app()
```

The app is also available directly through ShinyApps.io at:
<https://bit.ly/highdir>

------------------------------------------------------------------------

## Supported geometries

| Name | highcharter type | ggplot2 equivalent | Extra args |
|:---|:---|:---|:---|
| `column` | column | `geom_col()` | — |
| `ranked_bar` | column | `geom_col()` | `vs`, `aim`, `char_scale`, `min_frac` |
| `line` | line / spline | `geom_line()` | `smooth`, `dot_size`, `line_symbols` |
| `scatter` | scatter | `geom_point()` | `dot_size` |
| `arearange` | arearange | `geom_ribbon()` | `ymin`, `ymax` |
| `pie` | pie | `geom_bar()`, `coord_polar()` | `inner_size` |
| `stacked_column` | column | `geom_bar()`, `facet_wrap()` | `stack`, `stacking` |

------------------------------------------------------------------------

To see complete list of extra arguments for specify geoms use
`geom_args()` function:

``` r
geom_args("ranked_bar")
geom_args("arearange")
```

## License

MIT © Kamaleri