Tendril()
The Tendril function requires several arguments. The key argument is mydata a data frame with at least four columns, corresponding to a subject identifier, treatment arm, event type and day (relative to randomisation) of onset. Four character variables are also passed to denote the column name of the required columns; these are Unique.Subject.Identifier, Treat, Terms and StartDay respectively. If any additional columns are present then these are retained for subsequent analysis.
Additionally arguments are provided for the unadjusted angular displacement of each event (rotations, either a single value for all records or a vector which can vary by row of mydata); a minimum value for the number of events in at least one arm (AEfreqThreshold); a text label to apply to the analysis as a whole (Tag); the two treatments to be compared (Treatments, any other treatments are ignored).
A data frame can optionally be passed as the argument SubjList which lists all the subjects in the trial, including those not having an AE, and the corresponding treatments to which each subject has been randomised along with (optionally) the day to which each subject was followed up. Even though the SubjList data frame is optional, it is required to calculate statistics and simulate permuted tendrils (described below). Three character arguments (SubjList.subject, SubjList.treatment and SubjList.dropoutday) are then also passed to allow the variables in SubjList to be correctly identified.
Finally a number of binary flags can be passed to further control the analysis. compensate_imbalance_groups allows for treatment group imbalance to be compensated for, provided SubjList is present. filter_double_events allows either all, or just the first event of each type to be recorded for each subject. Finally, suppress_warnings allows warnings from the Chi-square test to be disabled, as low counts can result in multiple warning messages.
A typical Tendril dataset might look like this:
## subjid treatment ae day
## 1 ID240 placebo AE40 134
## 2 ID101 placebo AE43 263
## 3 ID101 placebo AE41 44
## 4 ID102 placebo AE37 134
## 5 ID102 placebo AE36 98
## 6 ID102 placebo AE39 50
Note the four columns containing the subject IDs (subjid), the treatment (treatment), the adverse effect term (ae) and the days (day).
The Tendril() function could then be called as:
test <- Tendril(mydata = TendrilData,
rotations = Rotations,
AEfreqThreshold = 9,
Tag = "Comment",
Treatments = c("placebo", "active"),
Unique.Subject.Identifier = "subjid",
Terms = "ae",
Treat = "treatment",
StartDay = "day",
SubjList = SubjList,
SubjList.subject = "subjid",
SubjList.treatment = "treatment"
)
NB: If there is any missing data in the subject identifier, treatment, event type or onset day then such rows will be removed.
The function checks that the arguments are valid and then computes the angles and coordinates of the x and y points in the tendrils based on the balance of events between treatments with the angular displacement being determined by the argument rotations.
The time between consecutive events of each type is proportional to the distance between connected points on the tendril plot. The angular displacement at each point is determined by the excess number of treatments on the first arm (rotating clockwise) or the excess number of treatments on the second arm (rotating anticlockwise) at each point in time.
If the argument SubjList provides a data frame of subjects, treatments and optionally drop-out days then Tendril calls the function tendril_stat to estimate the statistical significance of the imbalance at each data point. Statistical significance is estimated using an unadjusted Chi-square test (p), a Chi-square test false discovery rate (FDR) adjusted locally per AE (p.adj), or Fisher’s Exact test (fish). Additional statistics are provided for the risk difference (rdiff), risk ratio (RR) and odds ratio (OR).
TendrilPerm
The TendrilPerm function required an object of class Tendril to be passed (as tendril) which is the basis of permutations of the treatment assignment. An argument is also supplied with the event type (PermTerm) for which permutations are required. All other event types are ignored in the analysis and removed from the results.
Arguments can also be provided to specify the number of permutations (n.perm; defaults to 100), the day from which to permute treatments (perm.from.day; defaults to 1), the lower proportion to estimate (pi.low; defaults to 0.1, i.e. 10th percentile), and the upper proportion to estimate (pi.high; defaults to 0.9, i.e. 90th percentile).
As well as calculating permuted tendrils on the basis of randomly permuted treatment assignments (corresponding to a hypothesis of no imbalance between treatment arms) the TendrilPerm function also returns tendrils corresponding to the specified percentiles of these permutations. These facilitate comparison with the observed tendril to identify any event types with significant imbalance between treatment arms.
The use of the perm.from.day argument can be useful to explore temporal effects, for example where there is a strong imbalance initially, which subsequently resolves, with balanced incidence of events from a certain point in time onward.
The function outputs a list with four elements including the input tendril data filtered for the selected event type, the event type selected, the permuted tendril details, and the percentile details in the form of a TendrilPi object.
An example of an invocation of the TendrilPerm function, using the Tendril object generated above is as follows.
Plot functions
plot.Tendril
This function can be invoked as plot() applied to a Tendril object. As well as providing a Tendril object the user can optionally supply coloring and term arguments. coloring controls how the points on the tendril plot are coloured, and defaults to Terms meaning that each event type is coloured differently and a legend provided. Alternatively p, p.adj, FDR.tot, fish, rdiff, RR and OR will colour each point on the tendril scale according to the relevant statistic at that specific plot point.
The term argument allows the plot to display only specific event types. The default is NULL which means that all tendrils are displayed. Alternatively, a single value can be supplied, or a vector of multiple terms. In all cases tendrils are only displayed subject to the AEfreqThreshold argument.
The following plots illustrate some sample tendril plots.
These are generated using the ggplot2 package and so can be amended using features from the ggplot2 package.
Tendril plots can also be produced in interactive mode using the plotly package. These are requested by passing the optional argument interactive=TRUE. These interactive plots allow access to feature such as zooming, and hovering over points to obtain information such as the event type, the FDR p-value and the total number of events of that type.
plot.TendrilPerm
This function is also invoked as plot, but applied to a TendrilPerm object. As well as passing a TendrilPerm object the user can again specify a coloring argument. This applies equivalent colouring to that used in plot.Tendril but applied only to the selected event type, as defined in the call to TendrilPerm. Permuted tendrils are coloured in light grey.
There is also an optional percentile=TRUE argument which will overlay the percentiles specified in the call to TendrilPerm. These are shown as two dark grey lines.
The following plots illustrate example permutation plots.
Again, these plots are produced using ggplot2 and can be modified accordingly.
plot_timeseries
This function requires a Tendril object to be supplied and optionally a term argument, which defaults to NULL. The term argument operates in an equivalent manner to in the plot.Tendril function, and allows specific event types to be selected, unless NULL is supplied, in which case all tendrils are displayed.
The plot_timeseries function shows the event balance as a linear, rather than radial, plot, with time on the horizontal axis and the event balance on the vertical axis.
Example time series plots are shown below.
