Skip to content

Commit

Permalink
Don't use a hyphen in "size 1"
Browse files Browse the repository at this point in the history
  • Loading branch information
asmeurer committed May 22, 2024
1 parent a5add8b commit e3db1b6
Show file tree
Hide file tree
Showing 5 changed files with 18 additions and 18 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -671,7 +671,7 @@ Or if it had no actual `0`s:[^0-d-mask-footnote]
with the shape `(0,)` to the shape `(0,)`, and so this is what gets
assigned, i.e., "nothing" (of shape `(0,)`) gets assigned to "nothing" (of
matching shape `(0,)`). This is one reason why [broadcasting
rules](broadcasting) apply even to dimensions of size 0.
rules](broadcasting) apply even to dimensions of size `0`.

```py
>>> a = np.asarray([1, 1, 2])
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -522,8 +522,8 @@ axis, i.e., exactly the arrays we want.

This is why NumPy automatically broadcasts integer array indices together.

> **Outer indexing arrays can be constructed by inserting size-1 dimensions
> into the desired "outer" integer array indices so that the non-size-1
> **Outer indexing arrays can be constructed by inserting size `1` dimensions
> into the desired "outer" integer array indices so that the non-size `1`
> dimension for each is in the indexing dimension.**
For example,
Expand All @@ -540,7 +540,7 @@ Here, we use [newaxis](newaxis.md) along with `:` to turn `idx0` and
`idx1` into shape `(2, 1)` and `(1, 3)` arrays, respectively. These then
automatically broadcast together to give the desired outer index.

This "insert size-1 dimensions" operation can also be performed automatically
This "insert size `1` dimensions" operation can also be performed automatically
with the {external+numpy:func}`numpy.ix_` function.[^ix-footnote]

[^ix-footnote]: `ix_()` is currently limited to only support 1-D input arrays
Expand Down Expand Up @@ -647,7 +647,7 @@ For example, consider:
... [103, 104, 105]]])
```

This is the same `a` as in the above examples, except it has an extra size-1
This is the same `a` as in the above examples, except it has an extra size `1`
dimension:

```py
Expand Down
18 changes: 9 additions & 9 deletions docs/indexing-guide/multidimensional-indices/newaxis.md
Original file line number Diff line number Diff line change
Expand Up @@ -77,7 +77,7 @@ within the index `a[0, :2]`:

In each case, the exact same elements are selected: `0` always targets the
first axis, and `:2` always targets the second axis. The only difference is
where the size-1 axis is inserted:
where the size `1` axis is inserted:

```py
>>> a[np.newaxis, 0, :2]
Expand Down Expand Up @@ -127,11 +127,11 @@ its position in the tuple index after removing any `newaxis` indices.
Equivalently, `newaxis` indices can be though of as adding new axes *after*
the existing axes are indexed.

A size-1 axis can always be inserted anywhere in an array's shape without
A size `1` axis can always be inserted anywhere in an array's shape without
changing the underlying elements.

An array index can include multiple instances of `newaxis` (or `None`). Each
will add a size-1 axis in the corresponding location.
will add a size `1` axis in the corresponding location.

**Exercise:** Can you determine the shape of this array, given that `a.shape`
is `(3, 2, 4)`?
Expand All @@ -151,7 +151,7 @@ a[np.newaxis, 0, newaxis, :2, newaxis, ..., newaxis]

In summary,

> **`np.newaxis` (which is just an alias for `None`) inserts a new size-1 axis
> **`np.newaxis` (which is just an alias for `None`) inserts a new size `1` axis
in the corresponding location in the tuple index. The remaining,
non-`newaxis` indices in the tuple index are indexed as if the `newaxis`
indices were not there.**
Expand Down Expand Up @@ -184,12 +184,12 @@ array([[ 0],
`(3, 1)` column vector.

But the most common usage is due to [broadcasting](broadcasting). The key idea
of broadcasting is that size-1 dimensions are not directly useful, in the
of broadcasting is that size `1` dimensions are not directly useful, in the
sense that they could be removed without actually changing anything about the
underlying data in the array. So they are used as a signal that that dimension
can be repeated in operations. `newaxis` is therefore useful for inserting
these size-1 dimensions in situations where you want to force your data to be
repeated. For example, suppose we have the two arrays
these size `1` dimensions in situations where you want to force your data to
be repeated. For example, suppose we have the two arrays

```py
>>> x = np.array([1, 2, 3])
Expand Down Expand Up @@ -245,7 +245,7 @@ array([[101, 201],
[103, 203]])
```

Note: broadcasting automatically prepends size-1 dimensions, so the
Note: broadcasting automatically prepends size `1` dimensions, so the
`y[np.newaxis, :]` operation is unnecessary.

```py
Expand All @@ -255,7 +255,7 @@ array([[101, 201],
[103, 203]])
```

As we saw [before](single-axis-tuple), size-1 dimensions may seem redundant,
As we saw [before](single-axis-tuple), size `1` dimensions may seem redundant,
but they are not a bad thing. Not only do they allow indexing an array
uniformly, they are also very important in the way they interact with NumPy's
broadcasting rules.
Expand Down
4 changes: 2 additions & 2 deletions docs/indexing-guide/multidimensional-indices/tuples.md
Original file line number Diff line number Diff line change
Expand Up @@ -344,14 +344,14 @@ because it means that you can index the array
uniformly.[^size-1-dimension-footnote] And this doesn't apply just to
indexing. Many NumPy functions reduce the number of dimensions of their output
(for example, {external+numpy:func}`numpy.sum`), but they have a `keepdims`
argument to retain the dimension as a size-1 dimension instead.
argument to retain the dimension as a size `1` dimension instead.

[^size-1-dimension-footnote]: In this example, if we knew that we were always
going to select exactly one element (say, the second one) from the first
dimension, we could equivalently use `a[1, np.newaxis]` (see
[](../integer-indices.md) and [](newaxis.md)). The advantage of this is
that we would get an error if the first dimension of `a` didn't actually
have `2` elements, whereas `a[1:2]` would just silently give a size-0
have `2` elements, whereas `a[1:2]` would just silently give a size `0`
array.

There are two final facts about tuple indices that should be noted before we
Expand Down
4 changes: 2 additions & 2 deletions docs/indexing-guide/other-topics.md
Original file line number Diff line number Diff line change
Expand Up @@ -85,9 +85,9 @@ Broadcasting always happens automatically in NumPy whenever two arrays with
different shapes are combined using any function or operator, assuming those
shapes are broadcast compatible. The rule for broadcast compatibility is that
the shorter of the shapes are prepended with length 1 dimensions so that they
have the same number of dimensions. Then any dimensions that are size 1 in a
have the same number of dimensions. Then any dimensions that are size `1` in a
shape are replaced with the corresponding size in the other shape. The other
non-1 sizes must be equal or broadcasting is not allowed.
non-`1` sizes must be equal or broadcasting is not allowed.

In the above example, we broadcast `(3, 2)` with `(2,)` by first extending
`(2,)` to `(1, 2)` then broadcasting the size `1` dimension to the
Expand Down

0 comments on commit e3db1b6

Please sign in to comment.