Debian Codegraph @

pyvista/core/objects.py

raw
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