Package 'datasuite.ui'

Description

The shared interface of DataSuite's Shiny apps: chart options that restyle any 'ggplot2' chart (texts, fonts, colours, axes, legend, show or hide an element), a Word-like report builder writing Word, PowerPoint and PDF files, and the Shiny and React components, page frame and navigation the apps are built from. It holds nothing specific to one app's data: an app gives it its pages, its charts and its data through small interfaces.

Details

An app built on datasuite.ui gives it its pages, its data and its report content through small interfaces; the package itself knows nothing about any app's data and never calls an app's own package. The Countdown to 2030 apps are the working example: cd2030.core adds the Countdown pages and report content on top of it, and each app package (cd2030.rmncah, cd2030.vaxx, cd2030.pooled) has a run_app() built from both.

The app frame and components

app_frame() builds a whole app: the page, the sidebar and header, and the server. An app gives it a page registry (cd_page_def(), cd_use_pages()), a nav tree (cd_nav_section(), cd_nav_item()) and a data_server returning its dataset. A page is a module whose UI is cd_page_ui(), made of cards (cd_card(), cd_chart_card()), charts with their download and Customize tools (cd_plot_ui(), cd_plot_server()), inputs, dialogs and feedback. Every kit function is listed in ?"interface-kit"; the package README (the dataset contract, a minimal app) and docs/COMPONENTS.md in the repository describe each one.

Chart options

cd_chart_options() describes how a ggplot2 chart should look (texts, fonts, colours, axes, legend, grid, facets, marks, and showing or hiding each element) and apply_chart_options() applies it to a finished chart. merge_chart_options(), resolve_chart_options(), chart_option_fields() and cd_chart_type() support them.

Reports

A report is blocks on pages with a theme and a cover, edited in the browser (the Reports page, reports_ui() / reports_server()) and exported with export_report() (Word, PDF) or export_deck() (PowerPoint, PDF). An app registers what its reports offer once with report_register() (kinds of chart and table, standard reports, themes, fields) and gives the engine one dataset's data as a report_context(), or through an as_report_context() method for its own dataset class. Themes: report_themes(), report_theme_from_file(); fields: report_field_catalog().

Translations

Text is a translation key. cd_translations() merges the kit's keys, the files packages registered with cd_register_translations() and the app's own file for shiny.i18n::init_i18n(); cd_use_i18n() makes the translator the one the components use.

Author(s)

Maintainer: David Kariuki hello@damurka.com (ORCID)

Other contributors:

• African Population and Health Research Center (APHRC) [copyright holder, funder]

See Also

Useful links:

• https://github.com/damurka/datasuite.ui

• Report bugs at https://github.com/damurka/datasuite.ui/issues

Description

Apps built with app_frame() answer requests from DataSuite's chat (see docs/AI-BRIDGE.md). The frame has the built-in actions (the page, its charts and tables, navigation); an app adds its own with ai_action(), passed in app_frame(ai_actions = ).

Usage

ai_action(
  name,
  fn,
  kind = c("read", "view", "add", "replace", "change"),
  description = "",
  args = list(),
  classify = NULL,
  summary = NULL
)

Arguments

Value

An ai_action object.

Examples

ai_action("highlight", function(args, session) list(done = TRUE), kind = "view",
          description = "Highlight a region on the map", args = list(region = "a region name"))

Description

Registers a chart or table so DataSuite's chat can list it, read the data it shows and screenshot it (see docs/AI-BRIDGE.md). cd_plot_server() does this for every chart; call it for other outputs, e.g. a table, from their module server.

Usage

ai_register_component(
  session,
  output_id,
  type = c("chart", "table"),
  data,
  about = NULL,
  id = sub("-$", "", session$ns(""))
)

Arguments

Value

NULL, invisibly.

Description

A change the app asks the browser to make (open a page, set a filter) only shows in input after a round trip. An ai_action() returns ai_reply_when() to answer when ready() is TRUE, or after timeout seconds, with result().

Usage

ai_reply_when(ready, result, timeout = 3)

Arguments

Value

An object ai_action() functions return.

Description

Changes only what options sets (see cd_chart_options() for the list). The plot passed in is not modified. A plot that is not a ggplot (base graphics) is returned unchanged.

Usage

apply_chart_options(p, options = NULL)

Arguments

Value

The ggplot.

Description

What every report function calls on its first argument. A report_context is returned as it is and NULL gives an empty one; an app adds a method for its own dataset class.

Usage

as_report_context(x, ...)

Arguments

Value

A report_context.

Description

Describes what a user can change about a chart: its texts, fonts, sizes, colours, angles, legend, axes, grid, backgrounds and how its lines, points and labels are drawn. Every plot method in the package accepts one through its options argument (and any of these fields as a named argument in ...), and an app can keep them per chart, so the choices survive reloads.

Usage

cd_chart_options(
  ...,
  title = NULL,
  subtitle = NULL,
  caption = NULL,
  tag = NULL,
  x_title = NULL,
  y_title = NULL,
  legend_title = NULL,
  title_wrap = NULL,
  font_family = NULL,
  text_scale = NULL,
  line_height = NULL,
  title_size = NULL,
  subtitle_size = NULL,
  caption_size = NULL,
  axis_title_size = NULL,
  axis_text_size = NULL,
  x_title_size = NULL,
  y_title_size = NULL,
  x_text_size = NULL,
  y_text_size = NULL,
  legend_title_size = NULL,
  legend_text_size = NULL,
  strip_text_size = NULL,
  title_face = NULL,
  subtitle_face = NULL,
  caption_face = NULL,
  axis_title_face = NULL,
  axis_text_face = NULL,
  legend_title_face = NULL,
  legend_text_face = NULL,
  strip_text_face = NULL,
  text_color = NULL,
  title_color = NULL,
  subtitle_color = NULL,
  caption_color = NULL,
  axis_title_color = NULL,
  axis_text_color = NULL,
  legend_title_color = NULL,
  legend_text_color = NULL,
  strip_text_color = NULL,
  title_align = NULL,
  subtitle_align = NULL,
  caption_align = NULL,
  title_position = NULL,
  caption_position = NULL,
  x_text_angle = NULL,
  y_text_angle = NULL,
  plot_margin = NULL,
  legend_position = NULL,
  legend_direction = NULL,
  legend_justification = NULL,
  legend_ncol = NULL,
  legend_nrow = NULL,
  legend_reverse = NULL,
  legend_key_size = NULL,
  legend_background = NULL,
  legend_labels = NULL,
  legend_label_wrap = NULL,
  category_labels = NULL,
  category_label_wrap = NULL,
  x_limits = NULL,
  y_limits = NULL,
  x_labels = NULL,
  y_labels = NULL,
  axis_line = NULL,
  axis_line_color = NULL,
  axis_ticks = NULL,
  flip = NULL,
  grid = NULL,
  grid_minor = NULL,
  grid_color = NULL,
  grid_linewidth = NULL,
  grid_linetype = NULL,
  panel_border = NULL,
  panel_border_color = NULL,
  panel_color = NULL,
  background_color = NULL,
  strip_background = NULL,
  legend_border = NULL,
  legend_border_color = NULL,
  strip_border = NULL,
  strip_border_color = NULL,
  theme_preset = NULL,
  colors = NULL,
  line_scale = NULL,
  point_scale = NULL,
  alpha = NULL,
  bar_width = NULL,
  label_size = NULL,
  label_angle = NULL,
  label_color = NULL,
  facet_ncol = NULL,
  facet_nrow = NULL,
  facet_scales = NULL,
  strip_position = NULL,
  show_title = NULL,
  show_subtitle = NULL,
  show_caption = NULL,
  show_x_title = NULL,
  show_y_title = NULL,
  show_x_text = NULL,
  show_y_text = NULL,
  show_legend = NULL,
  show_legend_title = NULL,
  show_labels = NULL,
  show_strips = NULL
)

Arguments

Details

A field left NULL means "keep what the plot draws by default"; only what is set is changed. Text fields accept "", which hides that text and the space it took (as the ⁠show_*⁠ fields do). Colours are anything R understands ("red", "#1b7837", "transparent"). Sizes are in points unless said otherwise. ⁠x_*⁠ and ⁠y_*⁠ always mean the data's x and y aesthetics, so they follow the data when the chart is flipped.

Value

An object of class cd_chart_options (a list of the fields that are set).

See Also

apply_chart_options(), merge_chart_options()

Examples

cd_chart_options(title = "Coverage", legend_position = "bottom", text_scale = 1.2)
cd_chart_options(x_title = "Year", legend_labels = c(dhis2 = "Routine data"))
cd_chart_options(x_text_angle = 45, grid = "horizontal", grid_color = "grey90",
                 y_labels = "percent_points")

Description

A key made from the geoms a ggplot is built from (lines and points, bars, tiles...), used for a chart that has no id of its own.

Usage

cd_chart_type(p)

Arguments

Value

A string such as "geom:Errorbar+Line+Point", or NULL when p is not a ggplot with layers.

Description

The page assembled from its parts. Modules do not call this directly; they call cd_page_ui(), which fills in the title, section and subtitle from the page registry.

Usage

cd_page_body(
  dashboardId,
  dashboardTitle,
  i18n,
  ...,
  filters = NULL,
  include_report = FALSE,
  include_notes = FALSE,
  include_help = TRUE,
  eyebrow = NULL,
  subtitle = NULL,
  include_denominator = FALSE
)

Arguments

Description

An app starts a page's server the first time the page is opened (cd_pages_server()). What needs a page that may not have been opened (the AI reading a chart on another page) starts it with this. Nothing happens for a page already started, or in an app whose pages are all started with the session.

Usage

cd_start_pages(session = getDefaultReactiveDomain(), which = NULL)

Arguments

Value

NULL, invisibly.

Description

Tells whether a ggplot is split into panels (facet_wrap() or facet_grid()) and how they are laid out now, so an editor can offer the panel options of cd_chart_options() (facet_ncol, facet_nrow, facet_scales, strip_position) only for charts that have panels.

Usage

chart_facet_info(plot)

Arguments

Value

NULL when the chart has no panels. Otherwise a list with

• type: "wrap" or "grid";

• ncol, nrow: the number of columns and rows of panels as drawn (integer; NA when the plot cannot be built and the facet does not say);

• scales: "fixed", "free", "free_x" or "free_y";

• strip_position: "top", "bottom", "left" or "right" (for facet_grid(), where the column labels are, or the row labels when it only has rows);

• panels: the number of panels (integer, NA when the plot cannot be built).

Examples

library(ggplot2)
p <- ggplot(mtcars, aes(wt, mpg)) + geom_point() + facet_wrap(~cyl, ncol = 2)
chart_facet_info(p)
chart_facet_info(ggplot(mtcars, aes(wt, mpg)) + geom_point())

Description

Every field cd_chart_options() accepts, for code that keeps only the chart options out of a list of settings.

Usage

chart_option_fields()

Value

A character vector.

Description

What an app asks of DataSuite, the application running it: open the chat, print a page, install packages. Inside a Jovian R kernel whose host answers it (DataSuite starts the app with CDSUITE_HOST_UI=1), the request goes on Jovian's host channel as the method "datasuite.<action>" (hera::host_notify(), or hera::host_ask() to wait for the answer while the app keeps running); otherwise it is one line on the R session's output, ⁠DATASUITE_HOST_REQUEST <json>⁠, with the action in the JSON object beside args, and an answer is read from a done file named in the request. The requests, their arguments and answers are described in the package's docs/HOST-REQUESTS.md.

Usage

ds_host_request(action, args = list(), wait = FALSE, timeout = 120)

Arguments

Details

It asks whenever it is called: a caller checks first that the app runs inside DataSuite (CDSUITE_SHINY_ID is set, or CDSUITE_PRINT for printing).

Value

With wait = FALSE, TRUE invisibly once the request is sent. With wait = TRUE, DataSuite's answer (a list, as in the done file: ok, and error when it failed), or NULL when it gave none.

Examples

## Not run: 
ds_host_request("openChat", list(query = "Explain this chart: "))

## End(Not run)

Description

Draws every chart and table of a deck from the loaded data and writes it as a PowerPoint file, or as a PDF made from that file (by PowerPoint or LibreOffice, see report_deck_converter()), with the report builder's own writers (Quire's, through quire::quire_export()). Every item is placed at its box: text as text boxes in the design's fonts and colours, charts and pictures as pictures, tables as PowerPoint tables. The slides' speaker notes are kept.

Usage

export_deck(
  context,
  project,
  file,
  format = c("pptx", "pdf"),
  i18n = NULL,
  progress = NULL,
  converter = c("auto", "powerpoint", "libreoffice")
)

Arguments

Value

file, invisibly, with attribute converter (what made the PDF; NULL for a PowerPoint file).

Description

Draws every chart and table from the loaded data and writes the report as a Word document or a PDF, with the report builder's own writers (Quire's, through quire::quire_export()). The PDF is made from the Word file (see report_converter()), so the two match page for page. A slide deck (kind = "deck") is written by export_deck(), as a PowerPoint file or a PDF.

Usage

export_report(
  context,
  project,
  file,
  format = c("docx", "pdf", "pptx"),
  i18n = NULL,
  subtitle = NULL,
  progress = NULL,
  converter = c("auto", "word", "libreoffice", "browser", "powerpoint")
)

Arguments

Value

file, invisibly, with attribute converter: what made the PDF ("word", "libreoffice", "browser", "powerpoint") or, for Word, what finished the file ("word", or NULL).

Description

Later arguments win, field by field; legend_labels, category_labels and colors combine name by name. Use it to layer a dataset's defaults, a chart's saved options and what the caller passes now.

Usage

merge_chart_options(...)

Arguments

Value

A cd_chart_options object.

Examples

merge_chart_options(cd_chart_options(font_family = "serif", title = "A"),
                    cd_chart_options(title = "B"))

Description

Draw one chart or table of a report

Usage

render_report_block(context, block, i18n = NULL, design = NULL)

Arguments

Value

⁠list(type = "plot", value = <ggplot>)⁠, ⁠list(type = "table", value = <flextable>)⁠, or ⁠list(type = "error", message = <text>)⁠ when it cannot be drawn with this dataset.

Description

Apply a custom chart's transforms to its data

Usage

report_apply_transforms(data, transform = list())

Arguments

Value

The data frame, transformed. Stops with a message naming a missing column.

Examples

d <- data.frame(region = c("A", "B", "A"), year = c(2022, 2022, 2023), anc4 = c(50, 60, 55))
report_apply_transforms(d, list(list(filter = list(year = 2022)),
                               list(select = c("region", "anc4"))))

Description

The picture a block refers to as "asset:<id>" (see CacheConnection$set_report_asset()), for showing in a browser.

Usage

report_asset_data_url(context, id)

Arguments

Value

A ⁠data:⁠ URL, or NULL when the dataset has no such picture.

Description

Worked out from the page (see report_page()): a full-width block spans the text, a half-width one half of it. Shared by the builder's previews and by the exported files, so the page on screen and the file agree. A block on a slide carries its box, box = c(width, height) in inches (see report_project_blocks()): it is drawn at that size.

Usage

report_block_size(block, design = NULL)

Arguments

Value

c(width, height) in inches.

Description

What a standard report is written with. Texts may be plain strings or report_tx().

Usage

report_heading(text, level = 1)

report_paragraph(text)

report_note(text)

report_page_break()

report_chart(
  kind,
  indicator = NULL,
  admin_level = "national",
  size = "full",
  variant = NULL,
  type = "chart",
  region = NULL,
  year = NULL,
  title = NULL
)

report_table(kind, ...)

report_questions(
  ...,
  title = report_tx("Interpretations", "Interprétations", "Interpretações")
)

Arguments

Value

A block (a list).

Description

{chart_indicator} and {chart_year} in a text, heading or caption are the indicator (its name, in the report's language) and the year of the first chart or table after it in the report, so a title above a chart follows the chart when its indicator or year is changed. {chart_indicators} names the indicators of all the charts and tables after it up to the next heading ("ANC 4 Visits and Measles 1"), for a heading above charts side by side. A text with no chart after it keeps the field as typed.

Usage

report_chart_fields(blocks, context = NULL, i18n = NULL)

Arguments

Value

The blocks, their texts filled.

Description

Each argument is a function; those left out do nothing (no pictures kept, no saved chart options, no fields).

Usage

report_context(
  draw = NULL,
  asset_get = NULL,
  asset_set = NULL,
  chart_options = NULL,
  fields = NULL,
  years = NULL,
  regions = NULL,
  flag = NULL
)

Arguments

Value

An object of class report_context.

Description

Microsoft Word (Windows) or LibreOffice. With one of them the PDF has exactly the Word file's pages. (Quire's: quire::quire_converter().)

Usage

report_converter()

Value

"word", "libreoffice", or NULL when neither is installed.

Description

Microsoft PowerPoint (Windows) or LibreOffice. (Quire's: quire::quire_converter().)

Usage

report_deck_converter()

Value

"powerpoint", "libreoffice", or NULL when neither is installed.

Description

Where a new slide's placeholders go, as PowerPoint places them: each layout lists its boxes as fractions (0 to 1) of the slide's width and height, so they fit a 16:9 or a 4:3 slide.

Usage

report_deck_layouts(lang = NULL)

Arguments

Value

A list of layouts, each list(id, name, items); each item is list(role, type, x, y, w, h) with role "title", "subtitle", "heading", "body" or "picture" (a picture placeholder: nothing is written for it until a picture is put in it), and type "text" (a text box) or "content" (a text, chart, table or picture).

Description

The default cover page

Usage

report_default_cover()

Value

A cover (see the top of R/report-theme.R for its fields).

Description

The default report design

Usage

report_default_design()

Value

A design (see the top of R/report-theme.R for its fields).

Description

The report's own (title, date, editors, region, years, the chart below), then those the app registered (report_register(), fields).

Usage

report_field_catalog()

Value

A list of list(key, group, label); key is the word written in braces.

Description

The values of a report's fields

Usage

report_fields(context, project, date = Sys.Date(), lang = "en")

Arguments

Value

A named list of strings, one per field in report_field_catalog() that has a value.

Description

Writes the Word file, makes the PDF from it and renders each page as a picture: what the builder's "Final pages" view shows. Needs Microsoft Word or LibreOffice (report_converter()). For a slide deck, the PowerPoint file and its PDF (PowerPoint or LibreOffice, report_deck_converter()): one picture per slide.

Usage

report_final_pages(context, project, i18n = NULL, dpi = 60, progress = NULL)

Arguments

Value

⁠list(pages = <character vector of PNG files>, converter, pdf = <path>)⁠. The files are in a temporary folder the caller removes.

Description

Downloaded once from flagcdn.com and kept in the package's context folder. NULL when the country is not known or the flag cannot be downloaded (no internet): the cover is then drawn without it.

Usage

report_flag_file(iso3)

Arguments

Value

The path of a PNG file, or NULL.

Description

Typefaces made for print that come with Microsoft Office, so the page in the editor, the charts, the Word file and the PDF all use the same letters, on any computer that opens the file: serif faces for reading text, then sans serif faces for charts, tables and headings. Only those installed where the charts are drawn are given (all of them when that cannot be told).

Usage

report_fonts(group = c("all", "serif", "sans"), installed = TRUE)

Arguments

Value

A character vector.

Description

Every report_tx() in x (a block, a list of blocks, a cover...) replaced by its text in lang.

Usage

report_in(x, lang = "en")

Arguments

Value

x in that language.

Description

One kind of chart or table

Usage

report_kind(
  type,
  group,
  label,
  indicators = NULL,
  levels = NULL,
  variants = NULL,
  year = FALSE,
  regional = FALSE,
  groups = NULL,
  tall = FALSE
)

Arguments

Value

A list.

Description

The saved reports, as the AI lists them

Usage

report_list(projects)

Arguments

Value

A list, the last edited first, of list(id, name, kind, lang, blocks, updated); kind is "report" (a document) or "deck" (a slide deck), blocks the number of blocks (a deck's: of its slides' items).

Examples

report_list(list(r1 = list(name = "Coverage", blocks = list(report_paragraph("Hello")))))

Description

Field by field, b over a: lists such as a cover's editors or logos are replaced whole, not merged item by item.

Usage

report_merge(a, b)

Arguments

Value

The merged list.

Description

Page size, margins and the width and height left for content. Shared by the builder and the exported files.

Usage

report_page(design = report_default_design())

Arguments

Value

A list: width, height, top, bottom, left, right, text_width, text_height.

Description

Generic: a table in, a ggplot out. Chart options (the customize panel) apply to the result like to any other chart.

Usage

report_plot_spec(data, plot, title = NULL)

Arguments

Value

A ggplot.

Examples

d <- data.frame(region = c("A", "B"), value = c(55, 61))
report_plot_spec(d, list(geom = "col", x = "region", y = "value", percent = TRUE))

Description

A document's blocks, or every item's block of a slide deck, in order, so a caller can count, check or draw them the same way for both. A slide item's block gets the item's id and its box (box = c(width, height), inches), which report_block_size() draws it at. A document's free-layout page (a block of type "canvas", whose items are placed like a slide's) is given as its items' blocks, in the same way; the canvas block itself is not in the list.

Usage

report_project_blocks(project)

Arguments

Value

A list of blocks.

Description

Every block in order, compactly: its id and type; a heading's, paragraph's or note's text (plain, the formatting left out); a chart's or table's kind, settings, chart options and layout, and – with data = TRUE – a short table of what it shows (drawn as the report draws it: the chart's title, subtitle and caption, and the values it plots, or the table's rows), so the AI can write about it from its numbers.

Usage

report_read(
  context,
  project,
  id = project$id,
  i18n = NULL,
  lang = "en",
  data = TRUE,
  max_rows = 25,
  max_cols = 8,
  max_chars = 2000
)

Arguments

Value

list(id, name, kind, lang, region, blocks). A slide deck's blocks are its slides' items (each with its slide); a document's free page (canvas) lists its items' blocks in items.

Description

Called once by an app package (usually in its .onLoad()); later calls replace only what they give.

Usage

report_register(
  themes = NULL,
  default_theme = NULL,
  cover = NULL,
  kinds = NULL,
  presets = NULL,
  indicator_name = NULL,
  fields = NULL,
  chart_id = NULL
)

Arguments

Value

Invisibly, NULL.

Description

Puts the report's region in a block that asks for it (region = "@report"). A report without a region is a national report: such a block is then drawn for the whole country (or asks for a region when it needs one).

Usage

report_resolve_block(block, project, regions = NULL)

Arguments

Value

The block.

Description

The size of a slide deck's slides, in inches

Usage

report_slide_size(design = NULL)

Arguments

Value

c(width, height) in inches.

Description

Keeps a picture once in the dataset, from a ⁠data:⁠ URL (as the report builder uploads it) or from a web address (downloaded now, so the report does not need the internet later). A picture larger than 4000 pixels is made smaller; formats Word cannot show (WebP, for example) are converted to PNG.

Usage

report_store_asset(context, id, src)

Arguments

Value

A list: id, ratio (height / width) and url (a ⁠data:⁠ URL of the picture as stored), invisibly.

Description

Reads the colours and fonts of an Office theme or template (PowerPoint .pptx / .potx, Word .docx / .dotx) into a report theme, as report_themes() gives them: the accent is the theme's first accent colour, the text colour its first dark colour, the chart palette its six accent colours, the heading and body fonts its heading and body fonts. A Word file's styles give the heading colour (Heading 1's), the fonts and the text sizes when they set them, and its page size, orientation and margins. A PowerPoint file's master gives the title colour and fonts, the slide size and the background colour. The reading is Quire's (quire::quire_theme_from_file()).

Usage

report_theme_from_file(path, name = NULL)

Arguments

Details

The same file can be given to the export as the design's template (its path): see export_deck() and export_report().

Value

A design (see report_default_design()) with theme ("custom_<hash of the file>"), name (list(en, fr, pt)), and template_kind ("pptx" or "docx"); for a PowerPoint file also slide_size ("16:9" or "4:3", the nearer), background (the master's background colour, or NULL) and slide_designs: list(title, content), the look of the file's title slide and of its other slides (either NULL when not found). A slide design is list(background, decor, title, subtitle, body): background a colour or NULL; decor what is drawn behind a slide's content, back first, each list(type = "image", file, x, y, w, h) (a logo: file is the picture, copied out of the file into a temporary folder) or list(type = "rect", fill, fill_opacity, outline, x, y, w, h) (a band or bar), each also with from ("master", "layout" or "slide": where it was found); title, subtitle, body the style of that text, list(x, y, w, h, fill, fill_opacity, color, font_size, bold, align, font), or NULL. Boxes are in inches from the slide's top-left corner; colours are "#rrggbb". export_deck() draws a design's background and decor on its slides.

Description

The ready-made looks a report can start from. Each is a complete design (see report_default_design()).

Usage

report_themes()

Value

A named list of designs; each also has name.

Description

A translated string

Usage

report_translate(i18n, key, fallback = key)

Arguments

Value

A string.

Description

A standard report is written once, in the app's languages; report_in() gives it in one.

Usage

report_tx(en, fr = en, pt = en)

Arguments

Value

An object of class rb_tx.

Description

Applies targeted changes, in order, to a report's blocks, and checks the result as a whole (report_validate_project()). Only the blocks named change; the design, the cover and every other block stay as they are. Each change is one of:

Usage

report_update_blocks(
  project,
  changes,
  kinds = .ds_report_kinds(),
  members = NULL
)

Arguments

Details

• ⁠list(blockId, <fields>)⁠: changes that block.

  • A heading, paragraph or note: text (plain text; a line break starts a new line, ⁠**bold**⁠ is bold), type ("heading", "paragraph" or "note"), level (a heading's, 1 to 6), align, space_before, space_after (pt).

  • A chart or table: kind (another kind; the settings the new kind does not take are left out, those it needs get its defaults), its settings indicator, admin_level, region, year, variant (as the kind allows; NULL removes one), options (chart options, see cd_chart_options(); merged into the chart's own, NULL removes one), size ("full", "half", "third"), title (NULL: the chart's own), caption (FALSE hides the chart's caption).

  • A picture: caption, alt, size, width (percent of its column), align.

  • Any block of a document: pageBreakBefore (TRUE starts a new page before it, FALSE removes that).

• ⁠list(afterBlockId, insert = <block>)⁠: a new heading, paragraph, note, page break, chart or table after that block ("@start": at the start). Several inserted after the same block keep their order.

• list(blockId, delete = TRUE): removes the block.

• ⁠list(blockId, moveAfter = <id>)⁠: moves the block after another ("@start": to the start).

A slide deck's items can be changed, but not added, removed or moved.

Value

list(project, changes): the changed report (without its sigs on changed charts: the builder signs them again) and one sentence per change, saying what it did.

Examples

p <- list(name = "Notes", blocks = list(list(id = "b1", type = "paragraph", text = "")))
report_update_blocks(p, list(list(blockId = "b1", text = "Coverage rose."),
                             list(afterBlockId = "b1", insert = list(type = "heading", text = "Next steps"))))$changes

Description

Checks the shape of a report project (see export_report()) – one the AI built, say – before an app saves it: each block's type, and for charts and tables their kind. A custom_chart block may carry its description in spec or, as the AI bridge sends it, in options; either way it is checked with report_validate_spec() and kept in spec.

Usage

report_validate_project(project, kinds = NULL, members = NULL)

Arguments

Value

The project, tidied (each block has an id). Stops with a message saying what is wrong.

Examples

report_validate_project(list(name = "Notes", blocks = list(
  list(type = "heading", text = "Summary"),
  list(type = "paragraph", text = "Coverage rose.")
)))

Description

A custom chart (report kind "custom_chart") is described by data, never code: where its table comes from, a few fixed transforms and a plot description. report_validate_spec() checks one before it is saved, and returns it tidied (lists from JSON turned into vectors where a vector is meant).

Usage

report_validate_spec(spec, members = NULL)

Arguments

Value

The spec, tidied. Stops with a message saying what is wrong.

Examples

report_validate_spec(list(
  title = "Coverage by region",
  data = list(member = "calculate_coverage", args = list(admin_level = "adminlevel_1")),
  transform = list(list(filter = list(year = 2023))),
  plot = list(geom = "col", x = "adminlevel_1", y = "value")
))

Description

What every plot method calls with its options argument and its ...: options (an object, a list or NULL) plus any chart-option field named in ... (unrelated arguments in ... are ignored). Named arguments in ... win.

Usage

resolve_chart_options(options = NULL, ...)

Arguments

Value

A cd_chart_options object.

Description

Charts are written as SVG (vector: sharp at any size, on screen, printed or in the PDF Word makes) when the svglite package is installed and file ends in .svg; otherwise as PNG at dpi.

Usage

save_report_chart(rendered, block, file, dpi = 200, design = NULL)

Arguments

Value

file, invisibly.

Description

Run code with the report's saved chart options in effect

Usage

with_report_chart_options(context, code, design = NULL)

Arguments

Value

The value of code.