help tostsignrank
------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------


Title

    tostsignrank -- Test for the distribution of paired or matched data being equivalent to one that is symmetrical & centered on zero


Syntax

    Matched-pairs signed-ranks test for the distribution of paired or matched data being equivalent to one that is symmetrical & centered on zero

        tostsignrank varname = exp [if] [in] [, eqvtype(type) eqvlevel(#) uppereqvlevel(#) ccontinuity alpha(#) relevance]


    by is allowed with tostsignrank; see [D] by.


    tostsignrank options          Description
    ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
    Miscellaneous
      eqvtype(string)             specify equivalence threshold with Delta or epsilon
      eqvlevel(#)                 the level of tolerance defining the equivalence interval
      uppereqvlevel(#)            the upper value of an asymmetric equivalence interval
      ccontinuity                 include a continuity correction
      alpha(#)                    set nominal type I level; default is alpha(0.05)
      relevance                   perform & report combined tests for difference and equivalence
    ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------


Description

    tostsignrank tests the null hypothesis that the paired differences in measures are not symmetrically distributed and/or are not centered on the value of zero, and provides evidence for the distribution
    paired differences being equivalence to one that is symmetric and centered on zero.  tostsignrank uses the z approximation to the Wilcoxon matched-pairs signed-ranks test (Wilcoxon 1945) in a two
    one-sided tests approach (Schuirmann, 1987).

    With respect to the signed-rank test, a negativist null hypothesis takes one of the following two forms depending on whether tolerance is defined in terms of Delta (equivalence expressed in the same units
    as the signed ranks) or in terms of epsilon (equivalence expressed in the units of the z distribution):

        Ho: |T - E(T)| >= Delta,
        where the equivalence interval ranges from |T - E(T)|-Delta to |T - E(T)|+Delta, and where T is the signed-rank statistic and E(T) is its mean under the null.  This translates directly into two
        one-sided null hypotheses:

            Ho1: Delta - [T - E(T)] <= 0; and

            Ho2: [T - E(T)] + Delta <= 0

        -OR-

        Ho: |Z| >= epsilon,
        where the equivalence interval ranges from -epsilon to epsilon.  This also translates directly into two one-sided null hypotheses:

            Ho1: epsilon - Z <= 0; and

            Ho2: Z + epsilon <= 0

        When an asymmetric equivalence interval is defined using the uppereqvlevel option the general negativist null hypothesis becomes:

        Ho: [T - E(T)] <= Delta_lower, or [T - E(T)] >= Delta_upper,
        where the equivalence interval ranges from [T - E(T)] + Delta_lower to [T - E(T)] + Delta_upper.  This also translates directly into two one-sided null hypotheses:

            Ho1: Delta_upper - [T - E(T)] <= 0; and

            Ho2: [T - E(T)] - Delta_lower <= 0

        -OR-

        Ho: Z <= epsilon_lower, or Z >= epsilon_upper,

            Ho1: epsilon_upper - Z <= 0; and

            Ho2: Z - epsilon_lower <= 0
 
    NOTE: the appropriate level of alpha is precisely the same as in the corresponding two-sided test forevidence that paired differences are not symmetrically distributed and/or not centered on zero, so
    that, for example, if one wishes to make a type I error %5 of the time, one simply conducts both of the one-sided tests of Ho1 and Ho2 by comparing the resulting p-value to 0.05 (Wellek, 2010).

    For equivalence tests on unmatched data, see tostranksum.


Options

        +------+
    ----+ Main +------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

    eqvtype(string) defines whether the equivalence interval will be defined in terms of Delta or epsilon (delta, or epsilon).  These options change the way that evqlevel is interpreted: when delta is
        specified, the evqlevel is measured in the units of the signed rank sums, and when epsilon is specified, the evqlevel is measured in multiples of the standard deviation of the z distribution; put
        another way epsilon = Delta/standard error.  Because units of signed rank sums are unlikely to be substantively meaningful, the default is epsilon.

        Defining tolerance in terms of epsilon means that it is not possible to reject any test of mean equivalence Ho if epsilon <= the critical value of z for a given alpha.  Because epsilon = Delta/standard
        error, we can see that it is not possible to reject any Ho if Delta <= the product of the standard error and critical value of z for a given alpha.  tostsignrank reports when either of these conditions
        obtain.  Given that the variance of signed-rank distributions can be very large, tolerance should be specified using delta only with great care.

    eqvlevel(#) defines the equivalence threshold for the tests depending on whether eqvtype is delta or epsilon (see above).  Researchers are responsible for choosing meaningful values of Delta or epsilon.
        The default value is 1 (certain to be meaningless) when delta is the eqvtype and 2 when epsilon is the eqvtype.

    uppereqvlevel(#) defines the upper equivalence threshold for the test, and transforms the meaning of eqvlevel to mean the lower equivalence threshold for the test.  Also, eqvlevel is assumed to be a
        negative value.  Taken together, these correspond to Schuirmann's (1987) asymmetric equivalence intervals.  If uppereqvlevel==|eqvlevel|, then uppereqvlevel will be ignored.

    ccontinuity specifies that the test statistics incorporate a continuity correction using |T-E(T)|-0.5, but retaining the sign of the z-statistic after the correction has been applied (see eqvtype above).

    alpha(#) specifies the nominal type I error rate.  The default is alpha(0.05).

    relevance reports results and inference for combined tests for distributional difference and distributional equivalence for a specific alpha, eqvtype, and eqvlevel.  See the end of the Discussion section
        in tost for more details on inference from combined tests.


Remarks

    Following Tryon and Lewis (Tryon and Lewis 2008), when rejection decisions from both tests for difference and tests for equivalence are combined, there are four possible interpretations for a given alpha
    and epsilon or Delta:

    1.  One may reject the positivist Ho, but fail to reject the negativist Ho, and conclude that there is relevant difference between the distribution of paired differences and a distribution which is both
        symmetric and centered on zero which is at least as large as epsilon or Delta.

    2.  One may fail to reject the positivist Ho, but reject the negativist Ho, and conclude that there is equivalence between the distribution of paired differences and a distribution which is both symmetric
        and centered on zero within the equivalence range (i.e. defined by epsilon or Delta).

    3.  One may reject both the positivist Ho and the negativist Ho, and conclude that there is trivial difference between the distribution of paired differences and a distribution which is both symmetric and
        centered on zero which lies within the equivalence range (i.e. defined by epsilon or Delta).

    4.  One may fail to reject both the positivist Ho, and the negativist Ho, and draw an indeterminate conclusion, because the data are underpowered to detect either difference or equivalence.


Examples

    --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
    Example 1 setup
    .  webuse fuel

    1a Perform sign-rank relevance test between mpg1 and mpg2; equivalence
    interval is +/- 1.5 sd beyond the critical value of Z for alpha = 0.05
    epsilon = invnormal(.95)+1.5 = 3.1448536
    .  tostsignrank mpg1 = mpg2, eqvt(epsilon) eqvl(3.1448536) rel


    1b Same example, but using an asymmetric equivalence interval and continuity
    correction.  The lower end of the equivalence interval = invnormal(.95)+1.5
    = 3.1448536 meaning equivalence must lie no more than 1.5 sd beyond the
    critical value of Z for alpha = 0.05.  The upper end of the equivalence
    interval = invnormal(.95)+1 = 2.6448536 meaning equivalence must lie
    no more than 1 sd beyond the critical value of Z for alpha = 0.05.
    .  tostsignrank mpg1 = mpg2, eqvt(epsilon) eqvl(3.1448536) upper(2.6448536) cc rel
    --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------


Saved results

    signrank saves the following in r():

    Scalars   
      r(N_neg)       number of negative comparisons
      r(N_pos)       number of positive comparisons
      r(N_tie)       number of tied comparisons
      r(sum_pos)     sum of the positive ranks
      r(sum_neg)     sum of the negative ranks
      r(z1)          z statistic for Ho1 (upper)
      r(z1)          z statistic for Ho1 (upper)
      r(p2)          P(Z >= z1)
      r(p2)          P(Z >= z2)
      r(Var_a)       adjusted variance
      r(Delta)       Delta, tolerance level defining the equivalence interval; OR
      r(Du)          Delta_upper, tolerance level defining the equivalence interval's upper side; AND
      r(Dl)          Delta_lower, tolerance level defining the equivalence interval's lower side; OR
      r(epsilon)     epsilon, tolerance level defining the equivalence interval
      r(eu)          epsilon_upper, tolerance level defining the equivalence interval's upper side; AND
      r(el)          epsilon_lower, tolerance level defining the equivalence interval's lower side
      r(relevance)   Relevance test conclusion for given alpha and Delta/epsilon


Author

    Alexis Dinno
    Portland State University
    alexis.dinno@pdx.edu

    Development of tost is ongoing, please contact me with any questions, bug reports or suggestions for improvement.  Fixing bugs will be facilitated by sending along:

        (1) a copy of the data (de-labeled or anonymized is fine),
        (2) a copy of the command used, and
        (3) a copy of the exact output of the command.


Suggested citation

    Dinno, A.  2025.  tostsignrank: Test for the distribution of paired or matched data being equivalent to one that is symmetrical & centered on zero.  In: tost Stata software package.  URL: 
        https://www.alexisdinno.com/stata/tost.html


References

    Schuirmann, D. A.  1987.  A comparison of the two one-sided tests procedure and the power approach for assessing the equivalence of average bioavailability.  Journal of Pharmacokinetics and
        Biopharmaceutics.  15: 657-680

    Snedecor, G. W., and Cochran, W. G.  1989.  Statistical Methods.  8th ed.  Ames, IA: Iowa State University Press.

    Wellek, S.  2010.  Testing Statistical Hypotheses of Equivalence and Noninferiority, second edition.  Chapman and Hall/CRC Press. p. 31

    Wilcoxon, F.  1945.  Individual comparisons by ranking methods.  Biometrics Bulletin 1: 80-83


Also See

      Help: tost, pkequiv, signrank
