interpretation_set: Interpretation Sets
In jimvine/confinterpret: Descriptive Interpretations of Confidence Intervals

Description Usage Arguments Details Value

A class to define a set of interpretations for confidence intervals, depending on where the lower and upper confidence limits sit. A helper function for producing objects of this class.

1	interpretation_set(boundary_names, placeholders = NULL, interpretations)

`boundary_names`	Character vector of boundary names. The length of this vector (i.e., the number of boundary names listed) determines the number of boundaries for use with this interpretation_set, which also determines the number of interpretations that must be provided (see Details).
`placeholders`	Vector of named character elements, where each item contains a string that is used within the interpretations as a placeholder, enabling a specific value to be substituted. Can be null.
`interpretations`	An ordered list of interpretations, one for each valid combination of confidence limits. See Details for information on the number, format, and expected ordering of `interpretations` in a given `interpretation_set`.

The set of boundaries specified in an interpretation_set can be thought of as establishing a number of regions within which the lower and upper confidence limits can sit. There is 1 more region than the number of boundaries, since the set of regions is effectively 'less than boundary 1', 'between boundary 1 : n-1 and boundary 2 : n' and 'above boundary n'.

The valid combinations are those where the upper confidence limit is in a region greater than or equal to the region of the lower confidence limit. This establishes sum(1 : n) valid combinations, where n is the number of regions (i.e., the number of boundaries + 1). An interpretation needs to be provided for each of these combinations.

Interpretations are provided in order. The order is based on first specifying all the cases where the lower confidence limit is in the bottom region, and each of the regions for the upper confidence limit (again, starting from the bottom and increasing to the top); next come all of the cases where the lower confidence limit is in the second-from-bottom region (in this case the valid regions for the upper confidence limit will start at the second-from-bottom and go up to the top region); and so on. So for a 2 region (1 boundary) situation, the interpretations should be provided in the following order:

Order	Lower confidence level	Upper confidence level
1	Region 1	Region 1
2	Region 1	Region 2
3	Region 2	Region 2

For a 3 region (2 boundary) situation, the interpretations should be provided in this order:

Order	Lower confidence level	Upper confidence level
1	Region 1	Region 1
2	Region 1	Region 2
3	Region 1	Region 3
4	Region 2	Region 2
5	Region 2	Region 3
6	Region 3	Region 3

Each interpretation should itself be a list object containing named items: interpretation_short, interpretation, and interpretation_md. These contain, respectively, a short interpretation (one or two words), a version of the interpretation that would typically be a little longer (a short phrase), and the interpretation phrase with any markdown that is required. The markdown is typically used to emphasise the key words from the interpretation.

See the vignette on extending confinterpret for a worked example of how these list items are supplied.

Values for placeholders can be specified to enable sections of text in interpretations to be replaced automatically. This can be used, for example, to allow names or descriptions of interventions to be passed to confinterpret, so that these can be returned in the final interpretation rather than a generic description. confinterpret uses gsub with fixed=TRUE to do substitutions for placeholders entries, so values should be selected that will match accordingly (and will not match extra items). Use of a non-alphanumeric character within a placeholder can help to reduce accidental matches.

A plot method is provided for interpretation_set objects. See plot.interpretation_set for details.

A print method is provided for interpretation_set objects.

An object of class interpretation_set (a list object).

jimvine/confinterpret documentation built on May 19, 2019, 10:35 a.m.