NumPy Tutorial - Apêndice NumPy Array

O NumPy fornece numpy.append para adicionar valores a um array. Trata-se de uma função, não de um método ndarray.append, e ela retorna um novo array em vez de alterar o array de entrada no próprio lugar. As listas do Python têm métodos com nomes relacionados: list.append adiciona um objeto como um único item, enquanto list.extend adiciona cada item de um iterável. A função do NumPy segue regras de formato e eixo de arrays; por isso, as operações de lista servem como comparação, mas não podem ser usadas como chamadas intercambiáveis.

O que numpy.append faz

numpy.append combina um array de entrada com valores e retorna o resultado combinado. Por padrão, ela primeiro achata as duas entradas, de modo que o resultado é unidimensional, mesmo que os arrays originais tivessem várias dimensões. Ao informar um eixo, as outras dimensões são preservadas e a junção é feita nessa direção. Use o padrão quando quiser uma sequência plana; informe um eixo quando a disposição em linhas e colunas for importante.

Como a função retorna um novo array, guarde o valor retornado se precisar do resultado combinado. Por exemplo, atribua-o a uma nova variável ou atribua-o novamente à variável original. Chamar a função sem usar o valor retornado não atualiza arr.

Sintaxe e parâmetros

A assinatura é numpy.append(arr, values, axis=None) (comumente chamada como np.append após importar NumPy como np). arr é a entrada semelhante a um array que será ampliada. values contém os dados a adicionar e pode ser um escalar ou um objeto semelhante a um array. axis seleciona a dimensão ao longo da qual a junção será feita; por padrão, seu valor é None, que achata as duas entradas antes da junção. A função retorna um array.

Execute este exemplo. Os rótulos de entrada e saída exibidos no bloco permanecem em inglês; a saída mostra o array retornado:

import numpy as np

numbers = np.array([1, 2, 3])
combined = np.append(numbers, [4, 5])
print(combined)

[1 2 3 4 5]

Anexar sem um eixo

Quando axis é omitido ou definido como None, o NumPy achata arr e values antes de juntá-los. O resultado é unidimensional, independentemente das dimensões originais das entradas. Por exemplo, é possível combinar um array bidimensional com uma linha de valores sem preservar as linhas e colunas. Esse comportamento é útil para criar uma sequência plana, mas não insere uma linha ou coluna no arranjo original.

Se for importante preservar as dimensões do array, especifique um eixo em vez de depender do padrão. O achatamento pode permitir o uso conjunto de entradas com formatos diferentes, pois as dimensões são descartadas antes da combinação dos valores.

Anexar ao longo de um eixo

Em um array bidimensional, axis=0 adiciona linhas e axis=1 adiciona colunas. Os formatos das entradas devem coincidir em todas as dimensões, exceto naquela em que a junção é feita. Assim, para adicionar uma linha, a quantidade de colunas deve ser igual à do array existente; para adicionar uma coluna, a quantidade de linhas deve coincidir. Uma incompatibilidade gera ValueError, pois não é possível juntar os arrays mantendo as outras dimensões alinhadas.

Este exemplo adiciona uma linha. Os rótulos de entrada e saída exibidos nos blocos permanecem em inglês; o primeiro resultado mostra a linha acrescentada:

import numpy as np

matrix = np.array([[1, 2], [3, 4]])
with_row = np.append(matrix, [[5, 6]], axis=0)
print(with_row)

[[1 2]
 [3 4]
 [5 6]]

Todas as dimensões, exceto aquela indicada por axis, devem coincidir. Por exemplo, anexar uma linha com três colunas a uma matriz com duas colunas é incompatível e gera ValueError:

import numpy as np

matrix = np.array([[1, 2], [3, 4]])
try:
    np.append(matrix, [[5, 6, 7]], axis=0)
except ValueError as error:
    print(type(error).__name__)

Para adicionar uma coluna, passe um array bidimensional com uma linha para cada linha existente e uma coluna com os novos valores. Execute este exemplo. Os rótulos de entrada e saída exibidos no bloco permanecem em inglês:

import numpy as np

matrix = np.array([[1, 2], [3, 4]])
with_column = np.append(matrix, [[5], [6]], axis=1)
print(with_column)

[[1 2 5]
 [3 4 6]]

O resultado tem as mesmas duas linhas de matrix, com os novos valores em uma terceira coluna. Se a entrada anexada tiver uma quantidade incorreta de linhas, confira as dimensões antes de tentar novamente.