Adding new TLGs to the package • aNCA

This is an in-depth guide on contributing to the package. In order to get started with contributing, please read our contributing guide

Adding new Tables, Listing and Graphs

In order to add new TLGs, two things are needed: - a TLG definition specified in the tlg.yaml file - an implementation function that is responsible for generating an entry (table, list, graph).

TLG definition

Specified in tlg.yaml file. Entry in that file is responsible for providing some metadata regarding the TLG (like name, descriptions, links), a function reference for creating the resulting TLG and options, taken as arguments by the generating function, that allow for quick and easy definition of widgets to be rendered in the application interface. This then allows the user to customize plots in accordance to their needs.

General format

The entry should have the following format. Identifying keys (wrapped in <>) should be provided by the creator and be unique within their scope (indentation level).

# unique identifier for given entry
<entry id>:
  # true / false whether TLG should be included as default
  is_default:
  # type of the TLG, in this case must be Graph
  type:
  # name of the dataset
  dataset:
  # standarized id of the TLG, e.g. pkcg01     
  pkid:
  # short label to be displayed as tab name
  label:
  # longer descriptions, to be displayed in the order table
  description:
  # link to the documentation of the TLG
  link:
  # name of the function exported by the package, responsible for generating TLG, must return a list of plots to be displayed
  fun:
  # options that can be passed as arguments to the function, will generate an editing widget on the TLG page
  options:
    # see below mor more information on options
    
  template:
  # You can also specify template definitions. This is a character string with id of another TLG definition. All options will be copied over from template id. Any provided parameters will be a) overwritten if existing in the template or b) added as new.

Options

Options should be passable as arguments into the implementation function. Each provided option will generate a widget for the user to provide customized values. This is the main interface to allow the users to customize their reports. Options should be identified by a unique option_id, that is the same as the named argument provided to the implementation function. In example, if the implementation function allows to specify xaxis_label as an argument, the option_id should be the same.

There are several types of input widgets that you can specify.

text

Standard shiny textInput.

# option id, the same as the argument that is passed to the rendering function, must be unique in the scope of the TLG entry
<option id>:
  # type of the option/widget
  type: text
  # label to be displayed in the editing widget
  label:
  # default value to be provided in the field;
  # if provided, will overwrite function argument defaults;
  # if left empty, function defaults will be applied;
  default:

numeric

Standard shiny numericInput.

# option id, the same as the argument that is passed to the rendering function, must be unique in the scope of the TLG entry
<option id>:
  # type of the option/widget
  type: numeric
  # label to be displayed in the editing widget
  label:
  # default value to be provided in the field;
  # if provided, will overwrite function argument defaults;
  # if left empty, function defaults will be applied;
  default:

select

Standard shiny selectInput.

# option id, the same as the argument that is passed to the rendering function, must be unique in the scope of the TLG entry
<option id>:
  # type of the option/widget
  type: select
  # label to be displayed in the editing widget
  label:
  # choices to pick from the dropdown, either specified outright or using a special keyword:
  # - '.colnames' keyword will pull the choices from the data column names
  # - '$COLUMN_NAME' keyword will pull choices from values of a specific column
  choices:
  # whether to allow for multiple values to be selected  
  multiple:
  # default value to be provided in the field;
  # if provided, will overwrite function argument defaults;
  # if left empty, function defaults will be applied;
  # '.all' keyword can be applied to select all choices;
  default:

table

# option id, the same as the argument that is passed to the rendering function, must be unique in the scope of the TLG entry
<option id>:
  # type of the option/widget
  type: table
  # label to be displayed in the editing widget
  label: "Variables formatting"
  # column definition for the input table, specifying each column type
  cols:
    # colum name, as accepted in the implementation function
    <column_name>:
      # type of the input widget, either `text` or `select`
      type:
      # label for the column header
      label:
      # applicable to `select` type, choices to pick from the dropdown, either specified outright or using a special keyword:
      # - '.colnames' keyword will pull the choices from the data column names
      # - '$COLUMN_NAME' keyword will pull choices from values of a specific column
      choices:
  # default rows definition, should contain a list of rows that should be applied as defaults;
  # each row should be an array containing value for each defined column;
  # if row value for specific column should be empty, use special `$NA` keyword.
  default_rows:

group label

In order to group options widgets visually, you can specify group_labels in between the options definitions. Each group label should be specified by a special keyword .group_label_N, where N is an integer ID, incremented for each label used within the particular TLG entry.

# will create a label to help visually group related widgets; should be a character string; N should be replaced with an integer to uniquely identify the keyword    
.group_label_N:

Examples

For examples of TLG definition implementations, please see tlg.yaml file in the repository.

Implementation function

Function should be defined within aNCA package and meet the following criteria:

name should be prefaced with letter appropriate for tlg type:
- t_* for tables
- l_* for listings
- g_* for graphs
should accept a data argument for providing results to be rendered as a given TLG
should return a list of entries or a single entry.