## ----setup, include = FALSE--------------------------------------------------- knitr::opts_chunk$set( collapse = TRUE, comment = "#>", eval = FALSE # set TRUE for local preview ) ## ----caption-vs-description--------------------------------------------------- # library(highdir) # # opts <- hd_opts( # title = "Alcohol consumption over time", # subtitle = "Source: Norwegian Directorate of Health", # # # Visible below the chart — for citations and footnotes # caption = "Data: Hdir annual report 2023. Adjusted for population age.", # # # Read by screen readers only — describes what the chart shows # description = paste( # "Line chart showing adjusted mean alcohol consumption in Norway from", # "2010 to 2023. Consumption peaked at 7.3 litres per capita in 2014 and", # "declined steadily to 5.3 litres by 2023." # ) # ) ## ----data, eval = TRUE-------------------------------------------------------- library(highdir) # Single series — annual adjusted mean with 95% CI alcohol <- highdir::alco1 # columns: year, adj_mean, lower_95CI, upper_95CI # Grouped by sex alcohol2 <- highdir::alco2 # same columns + kjonn ## ----------------------------------------------------------------------------- # highdir:::.hd_accessibility(chart, description = opts$description) # ## ----hc-line-description, eval = TRUE----------------------------------------- spec_line <- hd_spec(alcohol, x = "year", y = "adj_mean") opts_line <- hd_opts( title = "Alcohol consumption in Norway", subtitle = "Source: Norwegian Directorate of Health", ylab = "Litres per capita", ylim = c(0, 40), description = paste( "Line chart showing adjusted mean alcohol consumption per capita in", "Norway from 2010 to 2023.", "Consumption peaked at approximately 7.3 litres in 2014 and declined", "to 5.3 litres by 2023, a reduction of 27 percent." ) ) # The description is embedded in the widget — invisible in the browser # but announced by screen readers # ------------------------------------------------------------------------------ # Layered approach hd(spec_line) + hd_geom_line() + opts_line # Declarative approach hd_make(spec_line, "line", opts_line) ## ----hc-line-grouped, eval = TRUE--------------------------------------------- spec_line2 <- hd_spec(alcohol2, x = "year", y = "adj_mean", group = "kjonn") opts_line2 <- hd_opts( title = "Alcohol consumption by sex", subtitle = "Source: Norwegian Directorate of Health", ylab = "Litres per capita", ylim = c(0, 50), description = paste( "Line chart comparing adjusted mean alcohol consumption per capita", "between men and women in Norway, 2010 to 2023.", "Men consistently drink more than women throughout the period.", "Both groups show a declining trend from 2014 onwards." ) ) hd_make(spec_line2, "line", opts_line2) ## ----hc-arearange, eval=TRUE-------------------------------------------------- opts_ar <- hd_opts( title = "Alcohol consumption with 95% confidence interval", subtitle = "Source: Norwegian Directorate of Health", ylab = "Litres per capita", ylim = c(0, 40), description = paste( "Area range chart showing adjusted mean alcohol consumption in Norway", "with 95 percent confidence intervals, 2010 to 2023.", "The shaded band represents uncertainty around the estimate.", "The interval is narrowest in the most recent years." ) ) # Layered approach hd(spec_line) + hd_geom_arearange(ymin = "lower_95CI", ymax = "upper_95CI") + opts_ar # Declarative approach hd_make(spec_line, "arearange", opts_ar, ymin = "lower_95CI", ymax = "upper_95CI") ## ----save-html---------------------------------------------------------------- # hc_fig <- hd_make(spec_line, "line", opts_line) # # # Description is embedded — the saved HTML file is fully accessible # hd_save(hc_fig, "alcohol_line.html") # # # selfcontained = TRUE (the default) embeds all JS/CSS so the file works # # without an internet connection — recommended for sharing # hd_save(hc_fig, "alcohol_line.html", selfcontained = TRUE) ## ----save-json---------------------------------------------------------------- # # The JSON file contains: # # { # # "title": { "text": "Alcohol consumption in Norway" }, # # "accessibility": { # # "description": "Line chart showing adjusted mean alcohol..." # # }, # # ... # # } # hd_save(hc_fig, "alcohol_line.json") ## ----gg-line-description------------------------------------------------------ # spec_line <- hd_spec(alcohol, # x = "year", # y = "adj_mean", # ylab = "Litres per capita") # # opts_gg <- hd_opts( # title = "Alcohol consumption in Norway", # subtitle = "Source: Norwegian Directorate of Health", # ylab = "Litres per capita", # ylim = c(0, 10), # description = paste( # "Line chart showing adjusted mean alcohol consumption per capita in", # "Norway from 2010 to 2023.", # "Consumption peaked at approximately 7.3 litres in 2014 and has", # "declined steadily since." # ) # ) # # gg_fig <- hd_make(spec_line, "line", opts_gg, backend = "ggplot2") # # # SVG preserves the description as a element — recommended # hd_save(gg_fig, "alcohol_line.svg") # # # PNG does not carry alt text — only use for contexts where accessibility # # is not required or where the alt text is set separately in the HTML # hd_save(gg_fig, "alcohol_line.png") ## ----alcohol-line, fig.alt = "Line chart showing alcohol consumption declining from 7.3 to 5.3 litres per capita between 2014 and 2023."---- # hd_make(spec_line, "line", opts_gg, backend = "ggplot2") ## ----alcohol-hc, fig.alt = "Interactive line chart of alcohol consumption."---- # hd_make(spec_line, "line", opts_line) ## ----good-description--------------------------------------------------------- # # Too vague — does not help a non-sighted user understand the finding # opts_vague <- hd_opts( # title = "Alcohol consumption", # description = "A chart about alcohol." # unhelpful # ) # # # Too long — screen readers become tedious to listen to # opts_too_long <- hd_opts( # title = "Alcohol consumption", # description = paste( # "This chart shows data from the Norwegian Directorate of Health about", # "alcohol consumption measured in litres per capita per year adjusted for", # "the age distribution of the population from the year 2010 through 2023", # "for the total population of Norway showing an increase from 6.2 litres", # "in 2010 to a peak of 7.3 litres in 2014 followed by a sustained", # "reduction to 5.3 litres in the year 2023." # too long # ) # ) # # # Well-written — chart type, subject, key finding, specific values # opts_good <- hd_opts( # title = "Alcohol consumption in Norway", # subtitle = "Source: Norwegian Directorate of Health", # ylab = "Litres per capita", # description = paste( # "Line chart of adjusted per capita alcohol consumption in Norway,", # "2010 to 2023. Consumption peaked at 7.3 litres in 2014 and fell to", # "5.3 litres by 2023." # ) # ) # # hd_make(spec_line, "line", opts_good) # hd_make(spec_line, "line", opts_good, backend = "ggplot2") ## ----grouped-description------------------------------------------------------ # opts_grouped <- hd_opts( # title = "Alcohol consumption by sex", # subtitle = "Source: Norwegian Directorate of Health", # ylab = "Litres per capita", # description = paste( # "Line chart comparing alcohol consumption between men and women in", # "Norway, 2010 to 2023. Men consume approximately twice as much as women", # "throughout the period. Both groups show a declining trend after 2014." # ) # ) # # hd_make(spec_line2, "line", opts_grouped) # hd_make(spec_line2, "line", opts_grouped, backend = "ggplot2")