| 1 |
"""Wrappers for :vtk:`vtkDataObject`. |
| 2 |
|
| 3 |
The data objects does not have any sort of spatial reference. |
| 4 |
|
| 5 |
""" |
| 6 |
|
| 7 |
from __future__ import annotations |
| 8 |
|
| 9 |
from typing import TYPE_CHECKING |
| 10 |
|
| 11 |
import numpy as np |
| 12 |
|
| 13 |
from pyvista import _vtk |
| 14 |
|
| 15 |
from .dataobject import DataObject |
| 16 |
from .datasetattributes import DataSetAttributes |
| 17 |
from .formatting_html import _data_array_section |
| 18 |
from .formatting_html import build_repr_html |
| 19 |
from .utilities.arrays import FieldAssociation |
| 20 |
from .utilities.arrays import FieldLiteral |
| 21 |
from .utilities.arrays import RowLiteral |
| 22 |
from .utilities.arrays import get_array |
| 23 |
from .utilities.arrays import row_array |
| 24 |
|
| 25 |
if TYPE_CHECKING: |
| 26 |
import pyarrow |
| 27 |
|
| 28 |
|
| 29 |
class Table(DataObject, _vtk.vtkTable): |
| 30 |
"""Wrapper for the :vtk:`vtkTable` class. |
| 31 |
|
| 32 |
Create by passing a 2D NumPy array of shape (``n_rows`` by ``n_columns``) |
| 33 |
or from a dictionary containing NumPy arrays. |
| 34 |
|
| 35 |
Examples |
| 36 |
-------- |
| 37 |
>>> import pyvista as pv |
| 38 |
>>> import numpy as np |
| 39 |
>>> arrays = np.random.default_rng().random((100, 3)) |
| 40 |
>>> table = pv.Table(arrays) |
| 41 |
|
| 42 |
""" |
| 43 |
|
| 44 |
def __init__(self, *args, deep: bool = True, **kwargs): # noqa: ARG002 |
| 45 |
"""Initialize the table.""" |
| 46 |
super().__init__() |
| 47 |
if len(args) == 1: |
| 48 |
if isinstance(args[0], _vtk.vtkTable): |
| 49 |
if deep: |
| 50 |
self.deep_copy(args[0]) |
| 51 |
else: |
| 52 |
self.shallow_copy(args[0]) |
| 53 |
elif isinstance(args[0], (np.ndarray, list)): |
| 54 |
self._from_arrays(args[0]) |
| 55 |
elif isinstance(args[0], dict): |
| 56 |
self._from_dict(args[0]) |
| 57 |
elif 'pandas.core.frame.DataFrame' in str(type(args[0])): |
| 58 |
self._from_pandas(args[0]) |
| 59 |
else: |
| 60 |
msg = f'Table unable to be made from ({type(args[0])})' |
| 61 |
raise TypeError(msg) |
| 62 |
|
| 63 |
@staticmethod |
| 64 |
def _prepare_arrays(arrays): |
| 65 |
arrays = np.asarray(arrays) |
| 66 |
if arrays.ndim == 1: |
| 67 |
return np.reshape(arrays, (1, -1)) |
| 68 |
elif arrays.ndim == 2: |
| 69 |
return arrays.T |
| 70 |
else: |
| 71 |
msg = 'Only 1D or 2D arrays are supported by Tables.' |
| 72 |
raise ValueError(msg) |
| 73 |
|
| 74 |
def _from_arrays(self, arrays) -> None: |
| 75 |
np_table = self._prepare_arrays(arrays) |
| 76 |
for i, array in enumerate(np_table): |
| 77 |
self.row_arrays[f'Array {i}'] = array |
| 78 |
|
| 79 |
def _from_dict(self, array_dict): |
| 80 |
for array in array_dict.values(): |
| 81 |
if not isinstance(array, np.ndarray) and array.ndim < 3: |
| 82 |
msg = 'Dictionary must contain only NumPy arrays with maximum of 2D.' |
| 83 |
raise ValueError(msg) |
| 84 |
for name, array in array_dict.items(): |
| 85 |
self.row_arrays[name] = array |
| 86 |
|
| 87 |
def _from_pandas(self, data_frame) -> None: |
| 88 |
for name in data_frame.keys(): |
| 89 |
self.row_arrays[name] = data_frame[name].values |
| 90 |
|
| 91 |
@property |
| 92 |
def n_rows(self): |
| 93 |
"""Return the number of rows. |
| 94 |
|
| 95 |
Returns |
| 96 |
------- |
| 97 |
int |
| 98 |
The number of rows. |
| 99 |
|
| 100 |
""" |
| 101 |
return self.GetNumberOfRows() |
| 102 |
|
| 103 |
@n_rows.setter |
| 104 |
def n_rows(self, n) -> None: |
| 105 |
"""Set the number of rows. |
| 106 |
|
| 107 |
Parameters |
| 108 |
---------- |
| 109 |
n : int |
| 110 |
The number of rows. |
| 111 |
|
| 112 |
""" |
| 113 |
self.SetNumberOfRows(n) |
| 114 |
|
| 115 |
@property |
| 116 |
def n_columns(self): |
| 117 |
"""Return the number of columns. |
| 118 |
|
| 119 |
Returns |
| 120 |
------- |
| 121 |
int |
| 122 |
The number of columns. |
| 123 |
|
| 124 |
""" |
| 125 |
return self.GetNumberOfColumns() |
| 126 |
|
| 127 |
@property |
| 128 |
def n_arrays(self): |
| 129 |
"""Return the number of columns. |
| 130 |
|
| 131 |
Alias for: ``n_columns``. |
| 132 |
|
| 133 |
Returns |
| 134 |
------- |
| 135 |
int |
| 136 |
The number of columns. |
| 137 |
|
| 138 |
""" |
| 139 |
return self.n_columns |
| 140 |
|
| 141 |
def _row_array(self, name=None): |
| 142 |
"""Return row scalars of a vtk object. |
| 143 |
|
| 144 |
Parameters |
| 145 |
---------- |
| 146 |
name : str |
| 147 |
Name of row scalars to retrieve. |
| 148 |
|
| 149 |
Returns |
| 150 |
------- |
| 151 |
numpy.ndarray |
| 152 |
Numpy array of the row. |
| 153 |
|
| 154 |
""" |
| 155 |
return self.row_arrays.get_array(name) |
| 156 |
|
| 157 |
@property |
| 158 |
def row_arrays(self): |
| 159 |
"""Return the all row arrays. |
| 160 |
|
| 161 |
Returns |
| 162 |
------- |
| 163 |
int |
| 164 |
The all row arrays. |
| 165 |
|
| 166 |
""" |
| 167 |
return DataSetAttributes( |
| 168 |
vtkobject=self.GetRowData(), |
| 169 |
dataset=self, # type: ignore[arg-type] |
| 170 |
association=FieldAssociation.ROW, |
| 171 |
) |
| 172 |
|
| 173 |
def keys(self): |
| 174 |
"""Return the table keys. |
| 175 |
|
| 176 |
Returns |
| 177 |
------- |
| 178 |
list |
| 179 |
List of the array names of this table. |
| 180 |
|
| 181 |
""" |
| 182 |
return self.row_arrays.keys() |
| 183 |
|
| 184 |
def items(self): |
| 185 |
"""Return the table items. |
| 186 |
|
| 187 |
Returns |
| 188 |
------- |
| 189 |
list |
| 190 |
List containing tuples pairs of the name and array of the table arrays. |
| 191 |
|
| 192 |
""" |
| 193 |
return self.row_arrays.items() |
| 194 |
|
| 195 |
def values(self): |
| 196 |
"""Return the table values. |
| 197 |
|
| 198 |
Returns |
| 199 |
------- |
| 200 |
list |
| 201 |
List of the table arrays. |
| 202 |
|
| 203 |
""" |
| 204 |
return self.row_arrays.values() |
| 205 |
|
| 206 |
def update(self, data) -> None: |
| 207 |
"""Set the table data using a dict-like update. |
| 208 |
|
| 209 |
Parameters |
| 210 |
---------- |
| 211 |
data : DataSetAttributes |
| 212 |
Other dataset attributes to update from. |
| 213 |
|
| 214 |
""" |
| 215 |
if isinstance(data, (np.ndarray, list)): |
| 216 |
# Allow table updates using array data |
| 217 |
data = self._prepare_arrays(data) |
| 218 |
data = {f'Array {i}': array for i, array in enumerate(data)} |
| 219 |
self.row_arrays.update(data) |
| 220 |
self.Modified() |
| 221 |
|
| 222 |
def pop(self, name): |
| 223 |
"""Pop off an array by the specified name. |
| 224 |
|
| 225 |
Parameters |
| 226 |
---------- |
| 227 |
name : int or str |
| 228 |
Index or name of the row array. |
| 229 |
|
| 230 |
Returns |
| 231 |
------- |
| 232 |
pyvista.pyvista_ndarray |
| 233 |
PyVista array. |
| 234 |
|
| 235 |
""" |
| 236 |
return self.row_arrays.pop(name) |
| 237 |
|
| 238 |
def __getitem__(self, index): |
| 239 |
"""Search row data for an array.""" |
| 240 |
return self._row_array(name=index) |
| 241 |
|
| 242 |
def _ipython_key_completions_(self): |
| 243 |
return self.keys() |
| 244 |
|
| 245 |
def get(self, index): |
| 246 |
"""Get an array by its name. |
| 247 |
|
| 248 |
Parameters |
| 249 |
---------- |
| 250 |
index : int or str |
| 251 |
Index or name of the row. |
| 252 |
|
| 253 |
Returns |
| 254 |
------- |
| 255 |
pyvista.pyvista_ndarray |
| 256 |
PyVista array. |
| 257 |
|
| 258 |
""" |
| 259 |
return self[index] |
| 260 |
|
| 261 |
def __setitem__(self, name, scalars) -> None: |
| 262 |
"""Add/set an array in the row_arrays.""" |
| 263 |
self.row_arrays[name] = scalars |
| 264 |
|
| 265 |
def _remove_array(self, _, key) -> None: |
| 266 |
"""Remove a single array by name from each field (internal helper).""" |
| 267 |
self.row_arrays.remove(key) |
| 268 |
|
| 269 |
def __delitem__(self, name) -> None: |
| 270 |
"""Remove an array by the specified name.""" |
| 271 |
del self.row_arrays[name] |
| 272 |
|
| 273 |
def __iter__(self): |
| 274 |
"""Return the iterator across all arrays.""" |
| 275 |
for array_name in self.row_arrays: |
| 276 |
yield self.row_arrays[array_name] |
| 277 |
|
| 278 |
def _get_attrs(self): |
| 279 |
"""Return the representation methods.""" |
| 280 |
attrs = [] |
| 281 |
attrs.append(('N Rows', self.n_rows, '{}')) |
| 282 |
return attrs |
| 283 |
|
| 284 |
def _repr_html_(self): |
| 285 |
"""Return a pretty representation for Jupyter notebooks. |
| 286 |
|
| 287 |
It includes header details and information about all arrays. |
| 288 |
|
| 289 |
""" |
| 290 |
sections: list[str] = [] |
| 291 |
|
| 292 |
# Row data arrays |
| 293 |
arrays: list[tuple[str, int, str, str, str]] = [] |
| 294 |
for i in range(self.n_arrays): |
| 295 |
key = self.GetRowData().GetArrayName(i) |
| 296 |
arr = row_array(self, key) |
| 297 |
ncomp = 0 if arr is None else arr.shape[1] if arr.ndim > 1 else 1 |
| 298 |
dtype = 'None' if arr is None else str(arr.dtype) |
| 299 |
range_str = '' |
| 300 |
if arr is not None and arr.size > 0 and np.issubdtype(arr.dtype, np.number): |
| 301 |
fmt = '{:.3e}' |
| 302 |
range_str = f'[{fmt.format(np.nanmin(arr))}, {fmt.format(np.nanmax(arr))}]' |
| 303 |
arrays.append((key, ncomp, dtype, '', range_str)) |
| 304 |
|
| 305 |
if arrays: |
| 306 |
sections.append(_data_array_section('Row Data', arrays)) |
| 307 |
|
| 308 |
return build_repr_html( |
| 309 |
obj_type='Table', |
| 310 |
mesh_type='ImageData', |
| 311 |
header_badges=[ |
| 312 |
f'{self.n_rows:,} rows', |
| 313 |
f'{self.n_arrays} arrays', |
| 314 |
], |
| 315 |
sections=sections, |
| 316 |
text_repr=self.head(display=False, html=False), |
| 317 |
) |
| 318 |
|
| 319 |
def __repr__(self): |
| 320 |
"""Return the object representation.""" |
| 321 |
return self.head(display=False, html=False) |
| 322 |
|
| 323 |
def __str__(self): |
| 324 |
"""Return the object string representation.""" |
| 325 |
return self.head(display=False, html=False) |
| 326 |
|
| 327 |
def to_pandas(self): |
| 328 |
"""Create a Pandas DataFrame from this Table. |
| 329 |
|
| 330 |
Returns |
| 331 |
------- |
| 332 |
pandas.DataFrame |
| 333 |
This table represented as a pandas dataframe. |
| 334 |
|
| 335 |
""" |
| 336 |
try: |
| 337 |
import pandas as pd # noqa: PLC0415 |
| 338 |
except ImportError: # pragma: no cover |
| 339 |
msg = 'Install ``pandas`` to use this feature.' |
| 340 |
raise ImportError(msg) |
| 341 |
data_frame = pd.DataFrame() |
| 342 |
for name, array in self.items(): |
| 343 |
data_frame[name] = array |
| 344 |
return data_frame |
| 345 |
|
| 346 |
def to_arrow(self) -> pyarrow.Table: |
| 347 |
"""Return this table as a :class:`pyarrow.Table`. |
| 348 |
|
| 349 |
Each row array becomes a column with the same name and dtype. |
| 350 |
|
| 351 |
Requires :mod:`pyarrow`. |
| 352 |
|
| 353 |
Returns |
| 354 |
------- |
| 355 |
pyarrow.Table |
| 356 |
This table represented as an Arrow Table. |
| 357 |
|
| 358 |
Notes |
| 359 |
----- |
| 360 |
1D contiguous numeric columns wrap the underlying VTK buffer |
| 361 |
zero-copy. Booleans, complex numbers, and strings go through |
| 362 |
pyvista's existing VTK conversion and are copied. Arrow buffers |
| 363 |
are immutable by contract, so consumers cannot mutate VTK memory |
| 364 |
through the returned table. |
| 365 |
|
| 366 |
Examples |
| 367 |
-------- |
| 368 |
>>> import numpy as np |
| 369 |
>>> import pyvista as pv |
| 370 |
>>> table = pv.Table({'a': np.arange(3), 'b': np.array([0.5, 1.5, 2.5])}) |
| 371 |
>>> table.to_arrow().schema.names |
| 372 |
['a', 'b'] |
| 373 |
|
| 374 |
""" |
| 375 |
try: |
| 376 |
import pyarrow as pa # noqa: PLC0415 |
| 377 |
except ImportError: # pragma: no cover |
| 378 |
msg = 'Install ``pyarrow`` to use this feature.' |
| 379 |
raise ImportError(msg) from None |
| 380 |
return pa.table({name: np.asarray(array) for name, array in self.items()}) |
| 381 |
|
| 382 |
def __arrow_c_stream__(self, requested_schema: object | None = None) -> object: |
| 383 |
"""Export via the Arrow PyCapsule interface. |
| 384 |
|
| 385 |
Implements `the Arrow PyCapsule interface |
| 386 |
<https://arrow.apache.org/docs/format/CDataInterface/PyCapsuleInterface.html>`_ |
| 387 |
by delegating to :meth:`to_arrow`, so pandas, polars, DuckDB, |
| 388 |
ibis, narwhals, and other Arrow-aware consumers can ingest this |
| 389 |
table directly. Scalar 1D columns cross the boundary zero-copy. |
| 390 |
|
| 391 |
Requires :mod:`pyarrow`. |
| 392 |
""" |
| 393 |
return self.to_arrow().__arrow_c_stream__(requested_schema) |
| 394 |
|
| 395 |
def save(self, *args, **kwargs): # pragma: no cover |
| 396 |
"""Save the table.""" |
| 397 |
msg = "Please use the `to_pandas` method and harness Pandas' wonderful file IO methods." |
| 398 |
raise NotImplementedError(msg) |
| 399 |
|
| 400 |
def get_data_range( # type: ignore[override] |
| 401 |
self, |
| 402 |
arr: str | None = None, |
| 403 |
preference: FieldLiteral | RowLiteral = 'row', |
| 404 |
) -> tuple[float, float]: |
| 405 |
"""Get the min and max of a named array. |
| 406 |
|
| 407 |
Parameters |
| 408 |
---------- |
| 409 |
arr : str, numpy.ndarray, optional |
| 410 |
The name of the array to get the range. If ``None``, the active scalar |
| 411 |
is used. |
| 412 |
|
| 413 |
preference : str, optional |
| 414 |
When scalars is specified, this is the preferred array type |
| 415 |
to search for in the dataset. Must be either ``'row'`` or |
| 416 |
``'field'``. |
| 417 |
|
| 418 |
Returns |
| 419 |
------- |
| 420 |
tuple |
| 421 |
``(min, max)`` of the array. |
| 422 |
|
| 423 |
""" |
| 424 |
if arr is None: |
| 425 |
# use the first array in the row data |
| 426 |
arr = self.GetRowData().GetArrayName(0) |
| 427 |
if isinstance(arr, str): |
| 428 |
arr = get_array(self, arr, preference=preference) # type: ignore[assignment] |
| 429 |
# If array has no tuples return a NaN range |
| 430 |
if arr.size == 0 or not np.issubdtype(arr.dtype, np.number): # type: ignore[attr-defined] |
| 431 |
return (np.nan, np.nan) |
| 432 |
# Use the array range |
| 433 |
return np.nanmin(arr), np.nanmax(arr) |
| 434 |
|
| 435 |
@property |
| 436 |
def is_empty(self) -> bool: # numpydoc ignore=RT01 |
| 437 |
"""Return ``True`` if the table has no rows and no columns. |
| 438 |
|
| 439 |
.. versionadded:: 0.45 |
| 440 |
|
| 441 |
Examples |
| 442 |
-------- |
| 443 |
>>> import pyvista as pv |
| 444 |
>>> import numpy as np |
| 445 |
>>> table = pv.Table() |
| 446 |
>>> table.is_empty |
| 447 |
True |
| 448 |
|
| 449 |
>>> arrays = np.random.default_rng().random((100, 3)) |
| 450 |
>>> table = pv.Table(arrays) |
| 451 |
>>> table.is_empty |
| 452 |
False |
| 453 |
|
| 454 |
""" |
| 455 |
return self.n_rows == 0 and self.n_columns == 0 |