Debian Codegraph @

examples/98-common/dataframe_export.py

raw
1 """
2 .. _dataframe_export_example:
3
4 Export Mesh Data to a DataFrame
5 -------------------------------
6
7 Convert a mesh's :attr:`point_data <pyvista.DataSet.point_data>` or
8 :attr:`cell_data <pyvista.DataSet.cell_data>` to a :class:`pandas.DataFrame`
9 or :class:`pyarrow.Table` for downstream analytics, export, or interactive
10 exploration in IDEs like Positron's Data Explorer, JupyterLab, or VS Code's
11 data viewer.
12
13 This example uses a classic CFD-style workflow: a scalar field and a vector
14 field attached to a mesh, then filtered / aggregated / exported using
15 pandas idioms.
16
17 """
18
19 import numpy as np
20 from pyvista import examples
21
22 # %%
23 # Load a mesh and attach some data
24 # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
25 # Use the hexbeam fixture mesh and attach a pressure scalar plus a
26 # velocity vector.
27
28 mesh = examples.load_hexbeam()
29 rng = np.random.default_rng(seed=0)
30 mesh.point_data['pressure'] = rng.normal(loc=100.0, scale=20.0, size=mesh.n_points)
31 mesh.point_data['velocity'] = rng.normal(size=(mesh.n_points, 3))
32
33 # %%
34 # Convert to a :class:`pandas.DataFrame`
35 # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
36 # ``mesh.to_pandas()`` returns one row per point. Multi-component arrays are
37 # expanded to one column per component, named ``{array_name}_{i}``.
38
39 df = mesh.to_pandas()
40 df.head()
41
42 # %%
43 # The DataFrame has ``n_points`` rows and one column per (expanded) array.
44
45 df.shape
46
47 # %%
48 # Ad-hoc analytics
49 # ~~~~~~~~~~~~~~~~
50 # Since we have a DataFrame, the full pandas API is available: filter,
51 # derive new columns, summarize.
52
53 velocity = df[['velocity_0', 'velocity_1', 'velocity_2']].to_numpy()
54 df['speed'] = np.linalg.norm(velocity, axis=1)
55 df[['pressure', 'speed']].describe()
56
57 # %%
58 # Find the 5 highest-pressure points.
59
60 df.nlargest(5, 'pressure')[['pressure', 'speed']]
61
62 # %%
63 # Cell-level export
64 # ~~~~~~~~~~~~~~~~~
65 # Pass ``association='cell'`` to export :attr:`~pyvista.DataSet.cell_data`
66 # instead. The result has ``n_cells`` rows.
67
68 mesh.cell_data['quality'] = rng.random(mesh.n_cells)
69 cell_df = mesh.to_pandas('cell')
70 cell_df.head()
71
72 # %%
73 # Export to disk
74 # ~~~~~~~~~~~~~~
75 # A DataFrame gives you one-liner access to every pandas I/O backend:
76 # Parquet, CSV, Feather, Excel, SQL, HDF5, and more. Commented out here to
77 # keep the gallery build clean.
78
79 # df.to_parquet('point_data.parquet')
80 # df.to_csv('point_data.csv', index=False)
81
82 # %%
83 # Zero-copy Arrow interchange
84 # ~~~~~~~~~~~~~~~~~~~~~~~~~~~
85 # ``mesh``, ``mesh.point_data``, ``mesh.cell_data``, and :class:`pyvista.Table`
86 # all implement the `Arrow PyCapsule interface
87 # <https://arrow.apache.org/docs/format/CDataInterface/PyCapsuleInterface.html>`_,
88 # so any Arrow-aware library (polars, DuckDB, ibis, narwhals) can consume them
89 # without pyvista depending on those libraries. For example, with pyarrow:
90 import pyarrow as pa
91
92 arrow_table = pa.table(mesh)
93 arrow_table.schema
94
95 # %%
96 # The ``mesh``, ``mesh.point_data``, and ``mesh.cell_data`` objects can also be
97 # opened directly in data-science IDE variable explorers (Positron, Jupyter,
98 # VS Code) after calling :meth:`~pyvista.DataSet.to_pandas`. The returned
99 # DataFrame renders as an interactive, sortable, filterable table.