HOWTO · NumPy

Convertir la série Pandas en tableau NumPy

Utilisez `Series.to_numpy()` pour convertir les valeurs d’une pandas Series en tableau NumPy ; son index reste séparé et n’est pas inclus dans le tableau.

Sur cette page

Une pandas Series stocke des valeurs accompagnées d’un index composé d’étiquettes. Pour obtenir un tableau NumPy contenant les valeurs, appelez Series.to_numpy() directement sur la Series. Les étiquettes ne sont pas incluses ; conservez ou convertissez l’index séparément si l’étape suivante en a besoin.

Convertir les valeurs d’une pandas Series en tableau NumPy avec Series.to_numpy()

Series.to_numpy() est le choix direct lorsqu’un ndarray NumPy est nécessaire. L’exemple crée une Series contenant deux valeurs numériques et leurs étiquettes, convertit les valeurs de la Series, puis examine le tableau obtenu et son dtype. Il affiche les valeurs [82 91] et indique que le dtype du tableau est int64.

Exécutez cet exemple :

Le code et les libellés ou sorties affichés dans cette section restent en anglais.

import pandas as pd

scores = pd.Series([82, 91], index=["Mia", "Noah"], name="score")
values = scores.to_numpy()
print(values)
print(values.dtype)
[82 91]
int64

Le tableau contient les valeurs dans l’ordre de la Series. Il ne contient ni "Mia" ni "Noah" ; ces étiquettes restent dans scores.index. Cette distinction compte lorsque vous transmettez les valeurs à une opération NumPy, qui travaille par position sans conserver les étiquettes pandas.

Utiliser Series.array lorsque vous avez besoin du tableau d’extension de pandas

Utilisez Series.array lorsque l’opération suivante doit recevoir la représentation sous forme de tableau de pandas. Selon les données de la Series, cette représentation peut être un tableau d’extension plutôt qu’un ndarray NumPy. Les tableaux d’extension préservent le comportement propre à pandas pour les types de données qui ne correspondent pas directement à un dtype NumPy conventionnel. Si l’API destinataire exige précisément un ndarray, utilisez plutôt Series.to_numpy().

Par exemple, l’expression scores.array accède à la représentation sous forme de tableau de la Series, tandis que scores.to_numpy() demande sa représentation NumPy. Ces choix répondent aux besoins de consommateurs différents : ne supposez pas que le résultat de Series.array est un ndarray et ne le transmettez pas à une API qui en exige un sans vérifier ses exigences.

Utiliser Series.values ou numpy.asarray() comme solutions compatibles

Series.values est une solution concise pour obtenir les valeurs de la Series sous la forme d’un objet assimilable à un tableau. Le résultat exact peut dépendre du dtype de la Series ; utilisez donc Series.to_numpy() si vous souhaitez une méthode de conversion explicite qui produit un ndarray NumPy. numpy.asarray(scores) est une autre façon compatible de demander un tableau à partir d’une Series ; elle est utile avec du code NumPy qui accepte déjà des objets assimilables à des tableaux.

Ces formes concernent les valeurs de la Series, et non ses étiquettes. Faites votre choix selon le contrat du code qui consomme le résultat : utilisez Series.to_numpy() pour obtenir clairement un ndarray, Series.array pour la représentation sous forme de tableau de pandas, ou Series.values et numpy.asarray() lorsque ces formes compatibles conviennent au code environnant. Aucune de ces options ne convertit l’index en tableau de valeurs.

Examiner le tableau obtenu et traiter séparément l’index et le dtype

Examinez le résultat lorsque le dtype a une incidence sur les calculs ou le stockage ultérieurs. Une Series numérique produit généralement un dtype NumPy numérique ; des valeurs représentées par des types propres à pandas ou des valeurs mixtes peuvent nécessiter une autre représentation NumPy. Vérifiez values.dtype pour connaître le résultat réel avec vos données, au lieu de supposer que toutes les Series produisent le même type de tableau. Aucun contrôle optionnel dtype ou copy n’est présenté ici, car les éléments fournis pour cette tâche n’établissent pas de recommandations propres à une version concernant les Series.

Si vous avez également besoin des étiquettes, accédez séparément à scores.index et préservez explicitement, dans votre programme, la correspondance entre les étiquettes et les valeurs. La conversion des seules valeurs élimine l’alignement par étiquette lors des opérations NumPy suivantes. C’est souvent le comportement voulu pour les traitements numériques, mais, si votre code combine les valeurs de plusieurs Series, vérifiez d’abord que leur ordre correspond. Une conversion de Series en tableau n’aligne pas automatiquement deux Series à partir de leurs étiquettes.