Source code for metatensor.labels

import ctypes
import io
import pathlib
from pickle import PickleBuffer
from typing import BinaryIO, List, Optional, Sequence, Tuple, Union, overload

import numpy as np

from ._c_api import mts_labels_t
from ._c_lib import _get_library
from .utils import _ptr_to_const_ndarray


[docs] class LabelsValues(np.ndarray): """ Wrapper class around the values inside :py:class:`Labels`, keeping a reference to the :py:class:`Labels` alive as needed. This class inherit from :py:class:`numpy.ndarray`, and can be used anywhere a numpy ndarray can be used. """ def __new__(cls, labels: "Labels"): array = _ptr_to_const_ndarray( ptr=labels._labels.values, shape=(labels._labels.count, labels._labels.size), dtype=np.int32, ) obj = array.view(cls) # keep a reference to the Python labels to prevent them from being # garbage-collected too early. obj._parent = labels return obj def __array_finalize__(self, obj): # keep the parent around when creating sub-views of this array self._parent = getattr(obj, "_parent", None) def __array_wrap__(self, new): self_ptr = self.ctypes.data self_size = self.nbytes new_ptr = new.ctypes.data if self_ptr <= new_ptr <= self_ptr + self_size: # if the new array is a view inside memory owned by self, wrap it in # LabelsValues return super().__array_wrap__(new) else: # otherwise return the ndarray straight away return np.asarray(new)
[docs] class LabelsEntry: """A single entry (i.e. row) in a set of :py:class:`Labels`. The main way to create a :py:class:`LabelsEntry` is to index a :py:class:`Labels` or iterate over them. >>> from metatensor import Labels >>> import numpy as np >>> labels = Labels( ... names=["structure", "atom", "species_center"], ... values=np.array([(0, 1, 8), (0, 2, 1), (0, 5, 1)]), ... ) >>> entry = labels[0] # or labels.entry(0) >>> entry.names ['structure', 'atom', 'species_center'] >>> print(entry.values) [0 1 8] """ def __init__(self, names: List[str], values: LabelsValues): assert isinstance(names, list) for n in names: assert isinstance(n, str) assert isinstance(values, LabelsValues) self._names = names if len(values.shape) != 1 or values.dtype != np.int32: raise ValueError( "LabelsEntry values must be a 1-dimensional array of 32-bit integers" ) self._values = values @property def names(self) -> List[str]: """names of the dimensions for this Labels entry""" return self._names @property def values(self) -> LabelsValues: """ values associated with each dimensions of this Labels entry, stored as 32-bit integers. """ return self._values @property def device(self) -> str: """ Get the device of this labels entry. This exists for compatibility with the TorchScript API, and always returns ``"cpu"`` when called. """ return "cpu"
[docs] def print(self) -> str: """ print this entry as a named tuple (i.e. ``(key_1=value_1, key_2=value_2)``) """ values = [f"{n}={v}" for n, v in zip(self.names, self.values)] return f"({', '.join(values)})"
def __repr__(self) -> str: return "LabelsEntry" + self.print() def __len__(self) -> int: """number of dimensions in this labels entry""" return self._values.shape[0] def __getitem__(self, dimension: Union[str, int]) -> int: """get the value associated with the dimension in this entry""" if isinstance(dimension, int): return self._values[dimension] elif isinstance(dimension, str): try: i = self._names.index(dimension) except ValueError: raise ValueError( f"'{dimension}' not found in the dimensions of these Labels" ) return self._values[i] else: raise TypeError( f"can only index LabelsEntry with str or int, got {type(dimension)}" ) def __eq__(self, other: "LabelsEntry") -> bool: """ check if ``self`` and ``other`` are equal (same dimensions/names and same values) """ if not isinstance(other, LabelsEntry): raise TypeError( f"can only compare between LabelsEntry for equality, got {type(other)}" ) return ( self._names == other._names and self._values.shape == other._values.shape and np.all(self._values == other._values) ) def __ne__(self, other: "LabelsEntry") -> bool: """ check if ``self`` and ``other`` are not equal (different dimensions/names or different values) """ return not self.__eq__(other)
[docs] class Labels: """ A set of labels carrying metadata associated with a :py:class:`TensorMap`. The metadata can be though as a list of tuples, where each value in the tuple also has an associated dimension name. In practice, the dimensions ``names`` are stored separately from the ``values``, and the values are in a 2-dimensional array integers with the shape ``(n_entries, n_dimensions)``. Each row/entry in this array is unique, and they are often (but not always) sorted in lexicographic order. >>> from metatensor import Labels >>> import numpy as np >>> labels = Labels( ... names=["structure", "atom", "species_center"], ... values=np.array([(0, 1, 8), (0, 2, 1), (0, 5, 1)]), ... ) >>> labels Labels( structure atom species_center 0 1 8 0 2 1 0 5 1 ) >>> labels.names ['structure', 'atom', 'species_center'] >>> print(labels.values) [[0 1 8] [0 2 1] [0 5 1]] It is possible to create a view inside a :py:class:`Labels`, selecting a subset of columns/dimensions: >>> # single dimension >>> view = labels.view("atom") >>> view.names ['atom'] >>> print(view.values) [[1] [2] [5]] >>> # multiple dimensions >>> view = labels.view(["atom", "structure"]) >>> view.names ['atom', 'structure'] >>> print(view.values) [[1 0] [2 0] [5 0]] >>> view.is_view() True >>> # we can convert a view back to a full, owned Labels >>> owned_labels = view.to_owned() >>> owned_labels.is_view() False One can also iterate over labels entries, or directly index the :py:class:`Labels` to get a specific entry >>> entry = labels[0] # or labels.entry(0) >>> entry.names ['structure', 'atom', 'species_center'] >>> print(entry.values) [0 1 8] >>> for entry in labels: ... print(entry) ... LabelsEntry(structure=0, atom=1, species_center=8) LabelsEntry(structure=0, atom=2, species_center=1) LabelsEntry(structure=0, atom=5, species_center=1) Or get all the values associated with a given dimension/column name >>> print(labels.column("atom")) [1 2 5] >>> print(labels["atom"]) # alternative syntax for the above [1 2 5] Labels can be checked for equality: >>> owned_labels == labels False >>> labels == labels True Finally, it is possible to check if a value is inside (non-view) labels, and get the corresponding position: >>> labels.position([0, 2, 1]) 1 >>> print(labels.position([0, 2, 4])) None >>> (0, 2, 4) in labels False >>> labels[2] in labels True """ def __init__(self, names: Union[str, Sequence[str]], values: np.ndarray): """ :param names: names of the dimensions in the new labels. A single string is transformed into a list with one element, i.e. ``names="a"`` is the same as ``names=["a"]``. :param values: values of the labels, this needs to be a 2-dimensional array of integers. """ names = _normalize_names_type(names) if not isinstance(values, np.ndarray): raise ValueError("`values` must be a numpy ndarray") if len(values) == 0: # make sure the array is 2D values = np.zeros((0, len(names)), dtype=np.int32) elif len(values.shape) != 2: raise ValueError("`values` must be a 2D array") if len(names) != values.shape[1]: raise ValueError( "`names` must have an entry for each column of the `values` array" ) try: # We need to make sure the data is C-contiguous to take a pointer to # it, and that it has the right type values = np.ascontiguousarray( values.astype( np.int32, order="C", casting="same_kind", subok=False, copy=False, ) ) except TypeError as e: raise TypeError("Labels values must be convertible to integers") from e self._lib = _get_library() self._labels = _create_new_labels(self._lib, names, values) self._names = names self._values = LabelsValues(self)
[docs] @staticmethod def single() -> "Labels": """ Create :py:class:`Labels` to use when there is no relevant metadata and only one entry in the corresponding dimension (e.g. keys when a tensor map contains a single block). """ return Labels(names=["_"], values=np.zeros(shape=(1, 1), dtype=np.int32))
[docs] @staticmethod def empty(names: Union[str, Sequence[str]]) -> "Labels": """ Create :py:class:`Labels` with given ``names`` but no values. :param names: names of the dimensions in the new labels. A single string is transformed into a list with one element, i.e. ``names="a"`` is the same as ``names=["a"]``. """ return Labels(names=names, values=np.array([]))
[docs] @staticmethod def range(name: str, end: int) -> "Labels": """ Create :py:class:`Labels` with a single dimension using the given ``name`` and values in the ``[0, end)`` range. :param name: name of the single dimension in the new labels. :param end: end of the range for labels >>> from metatensor import Labels >>> labels = Labels.range("dummy", 7) >>> labels.names ['dummy'] >>> print(labels.values) [[0] [1] [2] [3] [4] [5] [6]] """ return Labels( names=[name], values=np.arange(end, dtype=np.int32).reshape(-1, 1), )
@classmethod def _from_mts_labels_t(cls, labels: mts_labels_t): assert labels.internal_ptr_ is not None obj = cls.__new__(cls) obj._lib = _get_library() obj._labels = labels names = [] for i in range(labels.size): names.append(labels.names[i].decode("utf8")) obj._names = names obj._values = LabelsValues(obj) return obj def __del__(self): if hasattr(self, "_lib") and self._lib is not None: if hasattr(self, "_labels") and self._labels is not None: self._lib.mts_labels_free(self._labels) def __deepcopy__(self, _memodict): labels = mts_labels_t() self._lib.mts_labels_clone(self._labels, labels) return Labels._from_mts_labels_t(labels) def __copy__(self): return self.__deepcopy__({}) def __str__(self) -> str: printed = self.print(4, 3) if self.is_view(): return f"LabelsView(\n {printed}\n)" else: return f"Labels(\n {printed}\n)" def __repr__(self) -> str: printed = self.print(-1, 3) if self.is_view(): return f"LabelsView(\n {printed}\n)" else: return f"Labels(\n {printed}\n)" def __len__(self) -> int: """number of entries in these labels""" return self._values.shape[0] def __iter__(self): for i in range(len(self)): yield LabelsEntry(self._names, self._values[i, :]) @overload def __getitem__(self, dimension: str) -> np.ndarray: pass @overload def __getitem__(self, index: int) -> LabelsEntry: pass def __getitem__(self, index): """ When indexing with a string, get the values for the corresponding dimension as a 1-dimensional array (i.e. :py:func:`Labels.column`). When indexing with an integer, get the corresponding row/labels entry (i.e. :py:func:`Labels.entry`). See also :py:func:`Labels.view` to extract the values associated with multiple columns/dimensions. """ if isinstance(index, (int, np.int8, np.int16, np.int32, np.int64)): return self.entry(index) else: return self.column(index) def __contains__( self, entry: Union[LabelsEntry, Sequence[int]], ) -> bool: """check if these :py:class:`Labels` contain the given ``entry``""" if self.is_view(): raise ValueError( "can not call `__contains__` on a Labels view, call `to_owned` before" ) return self.position(entry) is not None def __eq__(self, other: "Labels") -> bool: """ check if two set of labels are equal (same dimension names and same values) """ if not isinstance(other, Labels): raise TypeError( f"can only compare between Labels for equality, got {type(other)}" ) return ( self._names == other._names and self._values.shape == other._values.shape and np.all(self._values == other._values) ) def __ne__(self, other: "Labels") -> bool: """ check if two set of labels are not equal (different dimension names or different values) """ return not self.__eq__(other) def _as_mts_labels_t(self): if self.is_view(): raise ValueError( "can not use a Labels view with the metatensor shared library, " "call `to_owned` before" ) else: return self._labels # ===== Serialization support ===== # @classmethod def _from_pickle(cls, buffer: Union[bytes, bytearray]): """ Passed to pickler to reconstruct Labels from bytes object """ from .io import load_labels_buffer return load_labels_buffer(buffer) def __reduce_ex__(self, protocol: int): """ Used by the Pickler to dump Labels object to bytes object. When protocol >= 5 it supports PickleBuffer which reduces number of copies needed """ from .io import _save_labels_buffer_raw buffer = _save_labels_buffer_raw(self) if protocol >= 5: return self._from_pickle, (PickleBuffer(buffer),) else: return self._from_pickle, (buffer.raw,)
[docs] @staticmethod def load(file: Union[str, pathlib.Path, BinaryIO]) -> "Labels": """ Load a serialized :py:class:`Labels` from a file, calling :py:func:`metatensor.load_labels`. :param file: file path or file object to load from """ from .io import load_labels return load_labels(file=file)
[docs] @staticmethod def load_buffer(buffer: Union[bytes, bytearray, memoryview]) -> "Labels": """ Load a serialized :py:class:`Labels` from a buffer, calling :py:func:`metatensor.io.load_labels_buffer`. :param buffer: in-memory buffer containing the data """ from .io import load_labels_buffer return load_labels_buffer(buffer=buffer)
[docs] def save(self, file: Union[str, pathlib.Path, BinaryIO]): """ Save these :py:class:`Labels` to a file, calling :py:func:`metatensor.save`. :param file: file path or file object to save to """ from .io import save return save(file=file, data=self)
[docs] def save_buffer(self) -> memoryview: """ Save these :py:class:`Labels` to an in-memory buffer, calling :py:func:`metatensor.io.save_buffer`. """ from .io import save_buffer return save_buffer(data=self)
# ===== Data manipulation ===== # @property def names(self) -> List[str]: """names of the dimensions for these :py:class:`Labels`""" return self._names @property def values(self) -> np.ndarray: """ values associated with each dimensions of the :py:class:`Labels`, stored as 2-dimensional tensor of 32-bit integers """ return self._values
[docs] def append(self, name: str, values: np.ndarray) -> "Labels": """Append a new dimension to the end of the :py:class:`Labels`. :param name: name of the new dimension :param values: 1D array of values for the new dimension >>> import numpy as np >>> from metatensor import Labels >>> label = Labels("foo", np.array([[42]])) >>> label Labels( foo 42 ) >>> label.append(name="bar", values=np.array([10])) Labels( foo bar 42 10 ) """ return self.insert(index=len(self), name=name, values=values)
[docs] def insert(self, index: int, name: str, values: np.ndarray) -> "Labels": """Insert a new dimension before ``index`` in the :py:class:`Labels`. :param index: index before the new dimension is inserted :param name: name of the new dimension :param values: 1D array of values for the new dimension >>> import numpy as np >>> from metatensor import Labels >>> label = Labels("foo", np.array([[42]])) >>> label Labels( foo 42 ) >>> label.insert(0, name="bar", values=np.array([10])) Labels( bar foo 10 42 ) """ new_names = self.names.copy() new_names.insert(index, name) if not isinstance(values, np.ndarray): raise ValueError("`values` must be a numpy ndarray") if len(values.shape) != 1: raise ValueError("`values` must be a 1D array") new_values = np.insert(self.values, index, values, axis=1) return Labels(names=new_names, values=new_values)
[docs] def permute(self, dimensions_indexes: List[int]) -> "Labels": """Permute dimensions according to ``dimensions_indexes`` in the :py:class:`Labels`. :param dimensions_indexes: desired ordering of the dimensions :raises ValueError: if length of ``dimensions_indexes`` does not match the Labels length :raises ValueError: if duplicate values are present in ``dimensions_indexes`` >>> import numpy as np >>> from metatensor import Labels >>> label = Labels(["foo", "bar", "baz"], np.array([[42, 10, 3]])) >>> label Labels( foo bar baz 42 10 3 ) >>> label.permute([2, 0, 1]) Labels( baz foo bar 3 42 10 ) """ if len(dimensions_indexes) != len(self.names): raise ValueError( f"the length of `dimensions_indexes` ({len(dimensions_indexes)}) does " f"not match the number of dimensions in the Labels ({len(self.names)})" ) names = [self.names[d] for d in dimensions_indexes] return Labels(names=names, values=self.values[:, dimensions_indexes])
[docs] def remove(self, name: str) -> "Labels": """Remove ``name`` from the dimensions of the :py:class:`Labels`. Removal can only be performed if the resulting :py:class:`Labels` instance will be unique. :param name: name to be removed :raises ValueError: if the name is not present. >>> import numpy as np >>> from metatensor import Labels >>> label = Labels(["foo", "bar"], np.array([[42, 10]])) >>> label Labels( foo bar 42 10 ) >>> label.remove(name="bar") Labels( foo 42 ) If the new :py:class:`Labels` is not unique an error is raised. >>> from metatensor import MetatensorError >>> label = Labels(["foo", "bar"], np.array([[42, 10], [42, 11]])) >>> label Labels( foo bar 42 10 42 11 ) >>> try: ... label.remove(name="bar") ... except MetatensorError as e: ... print(e) ... invalid parameter: can not have the same label value multiple time: [42] is already present at position 0 """ # noqa E501 if name not in self.names: raise ValueError(f"'{name}' not found in the dimensions of these Labels") new_names = self.names.copy() new_names.remove(name) index = self.names.index(name) new_values = np.delete(self.values, index, axis=1) return Labels(names=new_names, values=new_values)
[docs] def rename(self, old: str, new: str) -> "Labels": """Rename the ``old`` dimension to ``new`` in the :py:class:`Labels`. :param old: name to be replaced :param new: name after the replacement :raises ValueError: if old is not present. >>> import numpy as np >>> from metatensor import Labels >>> label = Labels("foo", np.array([[42]])) >>> label Labels( foo 42 ) >>> label.rename("foo", "bar") Labels( bar 42 ) """ if old not in self.names: raise ValueError(f"'{old}' not found in the dimensions of these Labels") names = self.names.copy() index = names.index(old) names[index] = new return Labels(names=names, values=self.values)
[docs] def to(self, device) -> "Labels": """ Move the values for these Labels to the given ``device``. In the Python version of metatensor, this returns the original labels. Defined for compatibility with the TorchScript version of metatensor. """ return self
@property def device(self) -> str: """ Get the device of these Labels. This exists for compatibility with the TorchScript API, and always returns ``"cpu"`` when called. """ return "cpu"
[docs] def position(self, entry: Union[LabelsEntry, Sequence[int]]) -> Optional[int]: """ Get the position of the given ``entry`` in this set of :py:class:`Labels`, or ``None`` if the entry is not present in the labels. """ if self.is_view(): raise ValueError( "can not call `position` on a Labels view, call `to_owned` before" ) result = ctypes.c_int64() c_entry = ctypes.ARRAY(ctypes.c_int32, len(entry))() for i, v in enumerate(entry): c_entry[i] = ctypes.c_int32(v) self._lib.mts_labels_position( self._labels, c_entry, c_entry._length_, result, ) if result.value >= 0: return result.value else: return None
[docs] def union(self, other: "Labels") -> "Labels": """ Take the union of these :py:class:`Labels` with ``other``. If you want to know where entries in ``self`` and ``other`` ends up in the union, you can use :py:meth:`Labels.union_and_mapping`. >>> import numpy as np >>> from metatensor import Labels >>> first = Labels(names=["a", "b"], values=np.array([[0, 1], [1, 2], [0, 3]])) >>> second = Labels(names=["a", "b"], values=np.array([[0, 3], [1, 3], [1, 2]])) >>> first.union(second) Labels( a b 0 1 1 2 0 3 1 3 ) """ if self.is_view() or other.is_view(): raise ValueError( "can not call `union` with Labels view, call `to_owned` before" ) output = mts_labels_t() self._lib.mts_labels_union( self._as_mts_labels_t(), other._as_mts_labels_t(), output, None, 0, None, 0 ) return Labels._from_mts_labels_t(output)
[docs] def union_and_mapping( self, other: "Labels" ) -> Tuple["Labels", np.ndarray, np.ndarray]: """ Take the union of these :py:class:`Labels` with ``other``. This function also returns the position in the union where each entry of the input :py:class::`Labels` ended up. :return: Tuple containing the union, a :py:class:`numpy.ndarray` containing the position in the union of the entries from ``self``, and a :py:class:`numpy.ndarray` containing the position in the union of the entries from ``other``. >>> import numpy as np >>> from metatensor import Labels >>> first = Labels(names=["a", "b"], values=np.array([[0, 1], [1, 2], [0, 3]])) >>> second = Labels(names=["a", "b"], values=np.array([[0, 3], [1, 3], [1, 2]])) >>> union, mapping_1, mapping_2 = first.union_and_mapping(second) >>> union Labels( a b 0 1 1 2 0 3 1 3 ) >>> print(mapping_1) [0 1 2] >>> print(mapping_2) [2 3 1] """ if self.is_view() or other.is_view(): raise ValueError( "can not call `union_and_mapping` with Labels view, call `to_owned` " "before" ) output = mts_labels_t() first_mapping = np.zeros(len(self), dtype=np.int64) second_mapping = np.zeros(len(other), dtype=np.int64) self._lib.mts_labels_union( self._as_mts_labels_t(), other._as_mts_labels_t(), output, first_mapping.ctypes.data_as(ctypes.POINTER(ctypes.c_int64)), len(first_mapping), second_mapping.ctypes.data_as(ctypes.POINTER(ctypes.c_int64)), len(second_mapping), ) return Labels._from_mts_labels_t(output), first_mapping, second_mapping
[docs] def intersection(self, other: "Labels") -> "Labels": """ Take the intersection of these :py:class:`Labels` with ``other``. If you want to know where entries in ``self`` and ``other`` ends up in the intersection, you can use :py:meth:`Labels.intersection_and_mapping`. >>> import numpy as np >>> from metatensor import Labels >>> first = Labels(names=["a", "b"], values=np.array([[0, 1], [1, 2], [0, 3]])) >>> second = Labels(names=["a", "b"], values=np.array([[0, 3], [1, 3], [1, 2]])) >>> first.intersection(second) Labels( a b 1 2 0 3 ) """ if self.is_view() or other.is_view(): raise ValueError( "can not call `intersection` with Labels view, call `to_owned` before" ) output = mts_labels_t() self._lib.mts_labels_intersection( self._as_mts_labels_t(), other._as_mts_labels_t(), output, None, 0, None, 0 ) return Labels._from_mts_labels_t(output)
[docs] def intersection_and_mapping( self, other: "Labels" ) -> Tuple["Labels", np.ndarray, np.ndarray]: """ Take the intersection of these :py:class:`Labels` with ``other``. This function also returns the position in the intersection where each entry of the input :py:class:`Labels` ended up. :return: Tuple containing the intersection, a :py:class:`numpy.ndarray` containing the position in the intersection of the entries from ``self``, and a :py:class:`numpy.ndarray` containing the position in the intersection of the entries from ``other``. If entries in ``self`` or ``other`` are not used in the output, the mapping for them is set to ``-1``. >>> import numpy as np >>> from metatensor import Labels >>> first = Labels(names=["a", "b"], values=np.array([[0, 1], [1, 2], [0, 3]])) >>> second = Labels(names=["a", "b"], values=np.array([[0, 3], [1, 3], [1, 2]])) >>> intersection, mapping_1, mapping_2 = first.intersection_and_mapping(second) >>> intersection Labels( a b 1 2 0 3 ) >>> print(mapping_1) [-1 0 1] >>> print(mapping_2) [ 1 -1 0] """ if self.is_view() or other.is_view(): raise ValueError( "can not call `intersection_and_mapping` with Labels view, call " "`to_owned` before" ) output = mts_labels_t() first_mapping = np.zeros(len(self), dtype=np.int64) second_mapping = np.zeros(len(other), dtype=np.int64) self._lib.mts_labels_intersection( self._as_mts_labels_t(), other._as_mts_labels_t(), output, first_mapping.ctypes.data_as(ctypes.POINTER(ctypes.c_int64)), len(first_mapping), second_mapping.ctypes.data_as(ctypes.POINTER(ctypes.c_int64)), len(second_mapping), ) return Labels._from_mts_labels_t(output), first_mapping, second_mapping
[docs] def print(self, max_entries: int, indent: int = 0) -> str: """print these :py:class:`Labels` to a string :param max_entries: how many entries to print, use ``-1`` to print everything :param indent: indent the output by ``indent`` spaces """ return _print_labels( self._names, self._values, max_entries=max_entries, indent=indent, )
[docs] def entry(self, index: int) -> LabelsEntry: """ Get a single entry/row in these labels. .. seealso:: :py:func:`Labels.__getitem__` as the main way to use this function """ return LabelsEntry(self._names, self._values[index, :])
[docs] def column(self, dimension: str) -> np.ndarray: """ Get the values associated with a single dimension in these labels (i.e. a single column of :py:attr:`Labels.values`) as a 1-dimensional array. .. seealso:: :py:func:`Labels.__getitem__` as the main way to use this function :py:func:`Labels.view` to access multiple columns simultaneously """ if not isinstance(dimension, str): raise TypeError( f"column names must be a string, got {type(dimension)} instead" ) try: index = self.names.index(dimension) except ValueError: raise ValueError( f"'{dimension}' not found in the dimensions of these Labels" ) return self.values[:, index]
[docs] def view(self, dimensions: Union[str, Sequence[str]]) -> "Labels": """ Get a view for the specified columns in these labels. .. seealso:: :py:func:`Labels.column` to get the values associated with a single dimension """ names = _normalize_names_type(dimensions) indices = [] for name in names: try: i = self.names.index(name) indices.append(i) except ValueError: raise ValueError( f"'{name}' not found in the dimensions of these Labels" ) values = self.values[:, indices] obj = self.__new__(Labels) obj._lib = _get_library() obj._labels = None obj._names = names obj._values = values return obj
[docs] def is_view(self) -> bool: """are these labels a view inside another set of labels? A view is created with :py:func:`Labels.__getitem__` or :py:func:`Labels.view`, and does not implement :py:func:`Labels.position` or :py:func:`Labels.__contains__`. """ return self._labels is None
[docs] def to_owned(self) -> "Labels": """convert a view to owned labels, which implement the full API""" labels = _create_new_labels(self._lib, self._names, self._values) return Labels._from_mts_labels_t(labels)
def _normalize_names_type(names: Union[str, Sequence[str]]) -> List[str]: """ Transform Labels names from any of the accepted types into the canonical representation (list of strings). """ if isinstance(names, str): if len(names) == 0: names = [] else: names = [names] else: try: names = list(names) except TypeError: raise TypeError( f"Labels names must be a sequence of strings, got {type(names)} instead" ) for name in names: if not isinstance(name, str): raise TypeError( f"Labels names must be strings, got {type(name)} instead" ) return names def _create_new_labels(lib, names: List[str], values: np.ndarray) -> mts_labels_t: labels = mts_labels_t() c_names = ctypes.ARRAY(ctypes.c_char_p, len(names))() for i, n in enumerate(names): c_names[i] = n.encode("utf8") labels.internal_ptr_ = None labels.names = c_names labels.size = len(names) labels.values = values.ctypes.data_as(ctypes.POINTER(ctypes.c_int32)) labels.count = values.shape[0] lib.mts_labels_create(labels) return labels def _print_string_center(output, string, width, last): delta = width - len(string) n_before = delta // 2 n_after = delta - n_before if last: # don't add spaces after the last element output.write(" " * n_before) output.write(string) else: output.write(" " * n_before) output.write(string) output.write(" " * n_after) def _print_labels( names: List[str], values: np.ndarray, max_entries: int, indent: int, ) -> str: # ================================================================================ # # Step 1: determine the width of all the columns (at least the width of the names # # plus 2, might be wider for large values) # # ================================================================================ # # the +2 is here use at least one space on each side of the name widths = [len(n) + 2 for n in names] # first set of values to print (before the "...") values_first = [] # second set of values to print (after the "...") values_second = [] n_elements = values.shape[0] # first, determine the width of each column by looking through all the # values and names lengths if max_entries < 0 or n_elements <= max_entries: for entry in values: entry_strings = [] for i, e in enumerate(entry): element_str = str(e) entry_strings.append(element_str) widths[i] = max(widths[i], len(element_str) + 2) values_first.append(entry_strings) else: if max_entries < 2: max_entries = 2 n_after = max_entries // 2 n_before = max_entries - n_after # values before the "..." for entry in values[:n_before, :]: entry_strings = [] for i, e in enumerate(entry): element_str = str(e) entry_strings.append(element_str) widths[i] = max(widths[i], len(element_str) + 2) values_first.append(entry_strings) # values after the "..." for entry in values[n_elements - n_after :, :]: entry_strings = [] for i, e in enumerate(entry): element_str = str(e) entry_strings.append(element_str) widths[i] = max(widths[i], len(element_str) + 2) values_second.append(entry_strings) # ================================================================================ # # Step 2: actually create the output string, using io.StringIO to incrementally # # append to the output # # ================================================================================ # indent_str = " " * indent n_dimensions = values.shape[1] output = io.StringIO() for i in range(n_dimensions): last = i == n_dimensions - 1 _print_string_center(output, names[i], widths[i], last) output.write("\n") for strings in values_first: output.write(indent_str) for i in range(n_dimensions): last = i == n_dimensions - 1 _print_string_center(output, strings[i], widths[i], last) output.write("\n") if len(values_second) != 0: half_header_widths = sum(widths) // 2 if half_header_widths > 3: # 3 characters in '...' half_header_widths -= 3 output.write(indent_str) output.write((half_header_widths + 1) * " ") output.write("...\n") for strings in values_second: output.write(indent_str) for i in range(n_dimensions): last = i == n_dimensions - 1 _print_string_center(output, strings[i], widths[i], last) output.write("\n") output = output.getvalue() assert output[-1] == "\n" return output[:-1]