*! version 0.4 23may2023

Title

What's new in artbin -- Changes from artbin version 1.1.2 to version 2.0.2

New features

A margin(#) option for 2-group trials has been included.

The user can now specify whether the outcome is favourable or unfavourable for a
2-arm trial.

The wald option has also been included for the Wald test.

The local option has been included for local alternatives, otherwise the default distant
will be used.

Sample size per group is now reported, and rounding up to the nearest integer is performed
per group.

A noround option has been included for the case when the user does not want artbin
to round the calculated sample size.

A loss to follow-up option is now available (ltfu(#)).

New syntax

Some improvements have been made to artbin. The user will need to alter previous coding using artbin to
accomodate the following changes.

The syntax for artbin has been updated to include a margin(#) option for 2-
group trials. For a non-inferiority/substantial-superiority trial the program will use pr(p1 p2) AND the new
option margin(#). For example, in the previous version (artbin 1.1.2) the syntax artbin, pr(.2 .3) ni(1)
will now be specified as artbin, pr(.2 .2) margin(.1). The option ni() is now redundant.

Previously local was taken as the default in superiority trials, now it is distant: the distant(#) option has been replaced by local in the syntax. Previous syntax (up to version 1.1.2) will need to be altered
so that artbin, pr(.1 .2) distant(1) will now be artbin, pr(.1 .2) and artbin, pr(.1 .2) distant(0)
will now be artbin, pr(.1 .2) local, for example.

The user is to identify whether the outcome is favourable or unfavourable in the context of a trial. With this information
plus the margin the program will then determine the type of trial (i.e. non-inferiority/substantial-superiority/superiority). If the user does
specify favourable/unfavourable the program will check the assumptions, if not then the program will infer it. The force
option can be used to override the program's inference of the favourability status, for example in the design of observational studies.

The wald option has also been included for the Wald test, as an alternative to the default score test.

Sample size per group is now reported, and rounding up to the nearest integer is performed per group. A noround option has been included for the case when the user does not want artbin to round the calculated sample size.
A loss to follow-up option is now available (ltfu(#)).

The option condit always implies the local option as there is no conditional distant option available in artbin. If the condit option is selected then local will be used (instead of the default distant).

The allocation ratio reects the fact that sample size is now rounded upwards in
each group rather than overall, and the expected number of events is calculated using the rounded sample size (unless the noround option for
calculated sample size is used).

Earlier versions of artbin required a number of yes/no options to be specified numerically,
e.g. onesided(1) or onesided(0). In updating the syntax, we have enabled the more standard options e.g.
onesided and ccorrect, but the numerical version of the syntax is retained if the user wishes to use it.

onesided is permitted for more than 2 groups if trend or dose is specified.

The number of groups is taken as the number of proportions in all cases and the ngroups(#) option is now redundant.
The mandatory option pr() is now a numlist instead of a string.

Changes have been made to the output table: now included in the description
is whether the trial is non-inferiority, substantial-superiority or superiority,
the trial outcome type, the statistical test assumed (including score or wald), whether local or distant
alternatives were used and the hypothesis tests and whether the continutity correction was used.
Minor formatting was also made to the existing allocation ratio, alpha, linear trend output and
version numbering output. Sample size per group is reported, and the returned values
have been streamlined to only include results as opposed to user-inputted options.

The text output has been changed from p0 and p1 to pi1 and pi2.
Therefore the control group event probability for non-inferiority trials is pi1.

Program structure

artbin calls a subroutine art2bin for all 2-group trials, which also allows for substantial-superiority
trials. Previously art2bin was only called for non-inferiority trials in artbin,
now it is called for all 2-group trials. art2bin can be used as a standalone but we do not
recommend this.

Authors

Abdel Babiker, MRC Clinical Trials Unit at UCL

Ab Babiker

Friederike Maria-Sophie Barthel, formerly MRC Clinical Trials Unit

Sophie Barthel

Babak Choodari-Oskooei, MRC Clinical Trials Unit at UCL

Babak Oskooei

Patrick Royston, MRC Clinical Trials Unit at UCL

Patrick Royston

Ella Marley-Zagar, MRC Clinical Trials Unit at UCL

Ella Marley-Zagar

Ian White, MRC Clinical Trials Unit at UCL

Ian White