# Pivotal dimensions

The concept of pivotal dimensions is probably the most complex aspect of the NSM language. Once understood its use will become easy. Be sure you understand the concept of multiple dimensions first. The purpose of the pivotal dimensions is to avoid programming with loops [is dit zo, I=of is dit het doel van de multiple dimensions?]. The iterations occur at a lower programming level over the pivotal dimensions, so the NSM programmer does not need many for or while loops.

The pivotal dimensions are used in two different ways:

1. For functions with one data argument, selecting one dimension for data manipulation (e.g. Mean, CumSum, ...)

2. For operators and function with two data arguments (e.g. +, hypot, ...)

### Pivotal dimensions for functions with one data argument

These functions involve a change in the amount of information stored in a matrix. They can be information-reduction functions, performing a mathematical or statistical operation that involves summarizing information contained in a range of values into a single value (e.g the sum, mean or number of values stored in a row or column). They can also be information-generation functions, like the expansion of a single value into a multi-dimensional matrix. In both cases, the pivotal dimensions are the dimensions that are, or should be affected by the data manipulation.

Examples ( pivotal dimensions in italics ):

```data = redim(1#20; 4, 5); // creates the following (4 x 5 ) matrix:

1  2  3  4  5

6  7  8  9 10

11 12 13 14 15

16 17 18 19 20
```

The command "redim" has ordered the range of values from 1 to 20 in a new way, adding information to the original values. Note that in this case the pivotal dimensions are not dimensions 4 and 5, but dimensions 1 and 2. The values 4 and 5 determine the length that these dimensions get by this command.

```
SumData1 = sum(data; 1); // creates the following (1x5) matrix:

34 38 42 46 50
```

The sum command has summed all values over the first dimension (pivotal dimension = 1), and the resulting matrix is a matrix with 2 dimensions, but with the size of the first dimensions reduced to 1. Note that in this case, the value 1 signifies which dimension is affected, not how it is affected.

When the pivotal dimension is omitted, data-reduction functions are performed over the last dimension (=default pivotal dimension). In the case of the current example, this would be the second dimension

```SumData2 = sum(data); // creates the following (4 x 1) matrix:

15

40

65

90
```

The resulting matrix has again two dimensions, and the size of the last dimension has been reduced to 1.

### Pivotal dimensions for operators and functions with two data arguments

The use of pivotal dimensions for operators and functions with two data arguments is similar to the functions with one data argument: the pivotal dimensions are the dimensions that determine how the two matrices are positioned against one another. The pivotal dimensions of the two data arguments should be chosen in such a way that all matching dimensions give a possible outcome. Matching dimensions usually have possible outcomes in two ways (when this is different, it is explained in the function): the dimensions can be of equal length, or at least one of the dimensions has length = 1. This can then be expanded to the required length. This rule is summarized in the following table:

 n = length of dimension of first argument m = length of dimension of second argument Condition Length of resulting dimension n[i]=0 m[i]=0 0 n[i]=<1 m[i]>=1 m[i] n[i]>1 m[i]>1 n[i]==m[i] n[i] n[i]>1 m[i]>1 n[i]<>m[i] Error

If a (pivotal) dimension is nonexistent it can be awarded length = 1. A negative index start counting backwards from the last dimension (e.g. the last dimension = -1), and may thus be used to append a dimension before the current ones. A positive index starts counting forward from the first dimension (e.g. the first dimension is 1), and may thus be used to append dimensions after the current ones.

### Example

Suppose we draw twice with a dice and sum their scores. What are the all the possible outcomes?

All different outcomes with a single draw are (1, 2, 3, 4, 5, 6). In table below are the summed outcome of drawing twice given:

 Second draw 1 2 3 4 5 6 First draw 1 2 3 4 5 6 7 2 3 4 5 6 7 8 3 4 5 6 7 8 9 4 5 6 7 8 9 10 5 6 7 8 9 10 11 6 7 8 9 10 11 12

How can we obtain this table in NSM?

```FirstDraw = redim(1,2,3,4,5,6; 6,1);  // this creates a matrix of 6 x 1

SecondDraw = redim(1,2,3,4,5,6; 1,6); // this creates a matrix of 1 x 6

SumDrawTwice = Plus(FirstDraw ; SecondDraw); // this results in a 6 x 6 matrix of all possible outcomes
```

How do we know the result of Plus(FirstDraw ; SecondDraw) is a (6 x 6) matrix and not a (6 x 1) or a (1 x 6) or even a (1 x 6 x 1) or (6 x 1 x 6)? No pivotal dimensions were made explicit in this command. Thus, the last dimensions of both matrices were the pivotal dimensions. To deduce the result write down the dimensions of the argument beneath each other, with the pivotal dimensions in the same column:

 Pivotal dimension – 1= first dimension PivotalDimension= last dimension Dimensions of FirstDraw 6 1 Dimensions of SecondDraw 1 6 In every column one of the dimensions has length = 1, so the result becomes: Dimensions of SumDrawTwice 6 6

Now what happens if we do make the pivotal dimensions explicit (values between brackets are appended)?

```SumDrawTwice = Plus(FirstDraw ; SecondDraw;1;1); // this results in a 6 x 6 matrix
```
 Pivotal dimension Pivotal dimension + 1 Dimensions of FirstDraw 6 1 Dimensions of SecondDraw 1 6 Dimensions of SumDrawTwice 6 6
```SumDrawTwice = Plus(FirstDraw ; SecondDraw;2;1);||// this results in a 6 x1x 6 matrix
```
 Pivotal dimension – 1 Pivotal dimension Pivotal dimension + 1 Dimensions of FirstDraw 6 1 (1) Dimensions of SecondDraw (1) 1 6 Dimensions of SumDrawTwice 6 1 6
```SumDrawTwice = Plus(FirstDraw ; SecondDraw;1;2); // this results in a 1x6 x1 matrix
```
 Pivotal dimension – 1 Pivotal dimension Pivotal dimension + 1 Dimensions of FirstDraw (1) 6 1 Dimensions of SecondDraw 1 6 (1) Dimensions of SumDrawTwice 1 6 1

So if we would want to know all the outcomes of the sum of drawing three times, the statements would become:

```Draw              = 1,2,3,4,5,6;                        // dimension 6
SumDrawTwice      = Plus(Draw; Draw; 1; 2);             // 6 and (6 x 1) => (6 x 6)
SumDrawThreeTimes = Plus(SumDrawTwice; Draw; -3; 1);    //  (1 x 6 x 6) and 6 => (6 x 6 x 6)
```

In the following table the whole pivotal arithmetic is summarized (values between brackets are appended):

 Pivotal dimension - 1 Pivotal dimension Pivotal dimension + 1 Draw (1) 6 Draw 6 1 SumDrawTwice 6 6 Pivotal dimension Pivotal dimension + 1 Pivotal dimension + 2 SumDrawTwice 1 6 6 Draw 6 (1) (1) SumDrawThreeTimes 6 6 6

An example of a command that leads to error is the following:

```TwoDraws = Redim(Draw; 2,6) // this doubles the 1x6 matrix to a 2x6 matrix
TestSum = Plus(Draw, TwoDraws; 1;1)
```
 Pivotal dimension Pivotal dimension + 1 Dimensions of FirstDraw 6 1 Dimensions of SecondDraw 2 6 Dimensions of SumDrawTwice Error!! 6