                       AMENDMENT: "A Change for the Better"
            (The American Heritage Dictionary of the English Language)

                                Donald B. McIntyre
                              Luachmhor, Church Road
                             Kinfauns, Perth PH2  7LD
                                 Scotland - U.K.
                             Telephone:  0738-86-726


        It used to be that whenever the computer centre manager decided to
        install a new version of the operating system, the FORTRAN
        compiler, or the APL interpreter, we were forced to interrupt what
        we were doing in order to adapt to the changed environment, even
        though we may have been content and comfortable with the old one.
        With a personal computer we change only when we choose to do so.
        Moreover, should we want to, we can have several versions of the
        software immediately available on the hard disk;  I can, for
        example, call up any one of ten different versions of Iverson and
        Hui's J interpreter.   All perform as originally specified and
        each has with it several executable script files.   It is helpful
        that J comes with two files (status.doc and xenos.doc) documenting
        the changes from all earlier versions.

        Because my paper on J's Boxed Arrays [1] was based on J Version
        3.3 [Reference 2 in the paper], I wish to explain where changes
        are required in order to execute under PC Version 5 (27 June
        1992).   For this purpose we can simulate the 5 by 6 array of
        nested cells previously used as a simple database:
           ]d=.<"0 i.5 6
        Ŀ
        0 1 2 3 4 5 
        Ĵ
        6 7 8 9 1011
        Ĵ
        121314151617
        Ĵ
        181920212223
        Ĵ
        242526272829
        
        The numbers identifying the cells can be called linear indexes, a
        term suggested to me by Eugene McDonnell.   Thus, defining the
        verb li (a fork):
           li=. [ { i.@$@]
        the linear indices of rows 1 and 4 are given by:
           1 4 li d
         6  7  8  9 10 11
        24 25 26 27 28 29

        And the linear index of the cell at row 2 and column 5:
           (<2 5) li d
        17

        The syntax now used for amend is illustrated by the following
        examples:

        To place the array x in this cell:
           x=. < 9 8 7 6,:5 4 3 2
           x 17} d
        Ŀ
        0 1 2 3 4 5      
        Ĵ
        6 7 8 9 1011     
        Ĵ
        12131415169 8 7 6
                  5 4 3 2
        Ĵ
        181920212223     
        Ĵ
        242526272829     
        
        Note that a noun (17) and an adverb (}) result in a verb.

        Scattered indexing presents no difficulty:
           (x;'London') ((2 5; 4 2) li d)} d
        Ŀ
        0 1 2     3 4 5      
        Ĵ
        6 7 8     9 1011     
        Ĵ
        121314    15169 8 7 6
                      5 4 3 2
        Ĵ
        181920    212223     
        Ĵ
        2425London272829     
        
        To expand the table and amend new rows 1 and 4:
           exp=. /:@\:@[ { #@[{.]
           e=. 1 0 1 1 0 1 1 exp d
           t=. e (1 li d)}~ 'Bob';'Bernecky';'Toronto';35;22000; 4 5
           t (4 li d)}~ 'Graham';'Woyka';'U.K.';62;35000;14 31 5 7
        Ŀ
        0     1       2      3 4    5        
        Ĵ
        Bob   BerneckyToronto35220004 5      
        Ĵ
        6     7       8      9 10   11       
        Ĵ
        12    13      14     1516   17       
        Ĵ
        GrahamWoyka   U.K.   623500014 31 5 7
        Ĵ
        18    19      20     2122   23       
        Ĵ
        24    25      26     2728   29       
        

        y=. ('Graham';'Woyka';'U.K.';1;2;3),:'Vin';'Grannell';'Los
        Angeles';4;5;6 7 8

           ]z=. e (1 4 li e)}~ 1 0{ y
        Ŀ
        0     1       2          3 4 5    
        Ĵ
        Vin   GrannellLos Angeles4 5 6 7 8
        Ĵ
        6     7       8          9 1011   
        Ĵ
        12    13      14         151617   
        Ĵ
        GrahamWoyka   U.K.       1 2 3    
        Ĵ
        18    19      20         212223   
        Ĵ
        24    25      26         272829   
        
        Alternatively:
              v=. 1 4&li
              v e
         6  7  8  9 10 11
        24 25 26 27 28 29
              u=. v@]}
              z-: e u~ 1 0{y
        1

        Although in these examples the indexes for amend are arbitrarily
        specified, they will often be computed as some function of the
        table;  as, for instance, in the computation of eigenvalues by
        Jacobi's method [2].

        Agreement:  Vector, Vol. 9, No. 3 (January 1993) p.137-140

        Given the following definitions:

              mean=. +/ % #
              f=. , mean
              a=. i.2 3 4 5

        Then a consists of 2 items, each of shape 3 4 5. The mean of a
        is the sum of the corresponding cells of these two items divided
        by 2. Its shape is therefore 3 4 5:

              $mean a
        3 4 5

        The hook f appends the means, consequently the shape is
        increased from 2 3 4 5 to 3 3 4 5:

              $f a
        3 3 4 5

        Because the rank of a is 4, the same result is produced by:

              $f"4 a
        3 3 4 5

        The rank conjunction (") lets us apply f to cells of rank 3, 2,
        or 1:

              $f"3 a
        2 4 4 5
              $f"2 a
        2 3 5 5
              $f"1 a
        2 3 4 6

        This is clearer when the results are displayed, but the space
        required is more than is justified here. In each case the shape
        of the result is the same as the shape of a except that the
        length of one axis is increased by 1. The example illustrates
        the impressive power of the rank conjunction.

        Given p and q:

              p=. i.2 3
              q=. 2 3

        then we can multiple the first row of p by 2 and the second row
        by 3

              p*"1 0 q
        0  2  4
        9 12 15

        where each cell of rank-1 in the left argument is multiplied by
        the corresponding rank-0 cell of the right argument. The
        sentence p*q formerly gave a length error, however the rule for
        agreement has been changed in J Version 5 so that now:

              p*q
        0  2  4
        9 12 15
              q*p
        0  2  4
        9 12 15

        The rule is that the "frames of the arguments must match, or one
        must be a prefix of the other" [3, p.6]. In this case the
        arguments agree because the frames of the rank-1 cells of p and
        of the rank-0 cells of q are both 2.

        Given:

              y=.i.5
              dev=. -mean

        Then the deviations from the mean are:

              dev y
        _2 _1 0 1 2

        The same result is returned when dev is written as:

              dev=. -"1 0 mean

        Because the right argument for the subtraction is rank-0 and the
        "ranks of a verb merely place upper limits on the ranks of the
        cells to which it is applied" [3, p.6], we can set the right
        rank to infinity (_):

              dev=. -"1 _ mean

        If y is rank-2:

        The earlier rule for agreement required the shorter frame to
        match the suffix of the longer frame. Consequently with

              dev=. - mean
              y=. i.4 5

        then,

              dev y

        which was formerly permitted [2, 4], now gives a length error.
        We must write, for example:

              dev=. -"1 _ mean         NB. right rank is at least 1
              $dev y
        4 5

        The 4 rank-1 cells (each of shape 5) are combined with the
        rank-1 cell (shape 5) resulting from mean y.

        If y is rank-3:

              y=. i.3 4 5

        then mean y is rank-2 and the deviations are computed by:

              dev=. -"2 _ mean         NB. right rank is at least 2

        The 3 rank-2 cells (each of shape 4 5) are combined with the
        rank-2 cell (shape 4 5) resulting from mean y.

        If y is rank-4:

              y=. i.2 3 4 5

        then mean y is rank-3 and the deviations are computed by

              dev=. -"3 _ mean
              $mean y
        3 4 5
              $dev y
        2 3 4 5

        The 2 rank-3 cells (each of shape 3 4 5) are combined with the
        rank-3 cell (chape 3 4 5) resulting from mean y.

        It is unsatisfactory that the definition of dev had to change as
        the rank of the argument changed. Because the computation of the
        mean involves summation, the rank of the result of  mean y  is
        always 1 less than the rank of y. In each example the rank of
        the result is the rank of the original argument, but the rank of
        the cells used in the subtraction is one less than this.
        Although the rank of the cells changes, the frame of the left
        argument is always of length 1; consequently we generalize by
        referring to the frame of the cells instead of to their rank.

        In J, "Negative numbers are used to specify cells whose frames
        are of length indicated by the magnitude of the number" [3,
        p.4]. In J Version 5 it is therefore possible to define a verb
        that applies to tables of any rank to give the deviations from
        the mean of items.

              dev=. -"_1 _ mean

        i.e. the following all execute correctly:

              dev ''
              dev 5
              dev i.5
              dev i.4 5
              dev i.3 4 5
              dev i. 2 3 4 5


        Acknowledgements:

        It is a pleasure once again to thank Ken Iverson and Roger Hui
        for continuing to provide interesting and useful amendments to
        their system, and for guidance on many matters relating to this
        paper.


        References:

        [1]  Donald B. McIntyre, Using J's Boxed Arrays. Vector, Vol.9,
             No.1 (July 1992) 92-105.

        [2]  Donald B. McIntyre, Jacobi's Method for Eigenvalues: an
             illustration of J. Vector Vol.9, No.3 (January 1993)
             125-133.

        [3]  Kenneth E. Iverson, Dictionary of J, Version 5 (1992)
             p.1-35, with Appendices p.1-18.

        [4]  Donald B. McIntyre, Mastering J, APL91 Conference
             Proceedings, Stanford, California, August 1991. APL Quote
             Quad Vol.21, No.4 (August 1991) p.264-273.

        [5]  Donald B. McIntyre, Language as an intellectual tool: From
             hieroglyphics to APL, IBM SYstems Journal, Vol.30, No.4 (1991)
             p.554-581.
