Topic: `APLX Help` : `Help on APL language` : `APL Primitives` : `[]Axis`
[ Previous | Next | Contents | Index | APL Home ] # `[``]` Axis

The highest dimension of a data item is considered to be the first dimension and the lowest dimension the last . Thus the first dimension of a matrix is the rows and the last dimension is the columns. In the case of a three-dimensional object, the first dimension is the planes followed by the rows and columns.

Axis numbers are governed by the Index Origin, `⎕IO,` and in Index Origin 1, (the default), the first dimension is represented by `,` the second by `` and so on. In Index Origin 0 the first dimension would be `,` the second `` and so on. The number used to represent the axis is always a whole number, except for the ravel and laminate functions.

The primitive functions and operators which will accept an axis specification include the dyadic forms of the primitive scalar functions :

```     + - × ÷ | ⌈ ⌊ * ⍟ ○ ! ^ ∨ ⍲ ⍱ < ≤ = ≥ > ≠
```

and some primitive mixed functions :

```     , ⍪       Ravel/Catenate/Laminate       (note first axis variant)
⌽ ⊖       Reverse/Rotate                (note first axis variant)
⊂         Enclose/Partition
⊃         Disclose
↑         Take
↓         Drop
⌷         Index
```

as well as the operators :

```     / ⌿       Compress/Replicate            (note first axis variant)
/ ⌿       Reduce                        (note first axis variant)
\ ⍀       Scan                          (note first axis variant)
\ ⍀       Expand                        (note first axis variant)
```

## Axis with scalar functions

When used with dyadic scalar functions (see above) the axis operator is placed after the function. The axis specified is a scalar or vector of axis numbers such that the number of axes specified is the same as the rank of the argument with the lower rank and all the axes specified must be found in the argument with the higher rank. Thus, for example, if the following expression is typed

```              vector  +[ AXES]   MATRIX
```

the left argument ( vector) is rank 1 and the right argument ( matrix) is of rank 2. The axes specified ( axes) can only be a scalar or vector of length 1 and (in index origin 1) that axis can only be 1 or 2 (one of the two dimensions of matrix).

```             A←⍳3                    (Vector A)
B←3 4⍴⍳12               (Matrix B)
A+[1 2]B                (Cannot have two axes specified with a
AXIS ERROR                     vector argument - the left argument)
A+[1 2]B
^
A+B                  (3 is higher than the highest dimension
AXIS ERROR                     of B - the higher rank argument)
A+B
^
A+B                  (Axis specification is valid for length
LENGTH ERROR                   and value, but the length of A - the
A+B                   lower rank argument - does not match the
^                        size of the second dimension of B - the
A+B                   columns)
2  3  4  5
7  8  9 10                   (A valid example)
12 13 14 15
B+A                  (The left or right argument may be of
2  3  4  5                    higher rank)
7  8  9 10
12 13 14 15
```
```             MAT←2 3 4⍴⍳24
MAT
1  2  3  4
5  6  7  8
9 10 11 12
```
```       13 14 15 16
17 18 19 20
21 22 23 24
1 10×MAT             (Vector multiplied across the first
1   2   3   4                dimension of MAT. Result has the same
5   6   7   8                shape as MAT)
9  10  11  12
```
```       130 140 150 160
170 180 190 200
210 220 230 240
TAB←2 3⍴1 5 10 10 50 100
TAB×[1 2]MAT            (Higher dimension example)
1    2    3    4
25   30   35   40
90  100  110  120
```
```        130  140  150  160
850  900  950 1000
2100 2200 2300 2400
TAB×[2 1]MAT            (Order of axes is immaterial)
1    2    3    4
25   30   35   40
90  100  110  120
```
```        130  140  150  160
850  900  950 1000
2100 2200 2300 2400
```

Multiple axis specifications cannot contain repetitions.

The next condition for axis with a scalar function is that the dimensions of the lower rank argument must be the same as the selected dimensions of the higher rank argument. When multiple axes are specified, they are used in ascending order, irrespective of the order in which they are entered.

Thus, for the example above, if vector is of length 5 and the axis specified is 1 (rows), then matrix must have 5 rows. If the axis specified is 2, matrix must have 5 columns.

Given correctly shaped arguments and valid axis specifications, the lower rank argument is applied across the dimensions of the higher rank argument specified by the axis operator. The result will have the shape of the higher rank argument.

## Axis with mixed functions and operators

When an operator or mixed function which accepts the axis operator is applied to data, it works on the last dimension, unless another dimension is specified. Alternatively, you can use the 'first-axis' functions and operators (see Ravel, Catenate, Rotate, Compress, Expand, Scan and Reduce) which are specially defined to apply by default to the first dimension. To specify a different dimension, enclose the number representing the dimension in square brackets, and put it after the operator or function.

```             TABLE
1  2  3  4                   (TABLE has 2 rows and 4 columns)
50 60 70 80
+/ TABLE                (No dimension is specified, so the
10 260                         add takes place on the last
dimension, ie across the columns
giving the sums of the rows)
+/ TABLE             (The first dimension is specified
51 62 73 84                    so the add is on the rows,
giving the sums of the columns.)
```
```             +\TABLE
1   3   6  10                (The operator acts on the last dimension)
50 110 180 260
```
```             TABLE,13 14             (TABLE is joined with the vector 13 14.
1  2  3  4 13                 This takes place at the last dimension,
50 60 70 80 14                 the columns making a new column)
```
```             TABLE, 13 14 15 16   (This vector is joined at the
1  2  3  4                    rows, making a new row.)
50 60 70 80
13 14 15 16
```
```             ⌽ TABLE                 (The rotation is across the
4  3  2  1                    columns. The same effect could be
80 70 60 50                    achieved by ⌽TABLE)
```
```             ⌽TABLE               (The rotation is across the rows)
50 60 70 80
1  2  3  4
```

Topic: `APLX Help` : `Help on APL language` : `APL Primitives` : `[]Axis`
[ Previous | Next | Contents | Index | APL Home ]