DenseTraitMatrix

class pybrops.core.mat.DenseTraitMatrix.DenseTraitMatrix(mat, trait=None, **kwargs)

Bases: DenseMutableMatrix, TraitMatrix

A concrete class for dense matrices with trait metadata.

The purpose of this concrete class is to implement base functionality for:

1. Dense matrix trait metadata.

2. Dense matrix trait routines.

Constructor for the concrete class DenseTraitMatrix.

Parameters:

• mat (numpy.ndarray) – A numpy.ndarray used to construct the object.

• trait (numpy.ndarray, None) – A numpy.ndarray of shape (t,) containing trait names. If None, do not store any trait name information.

• kwargs (dict) – Additional keyword arguments.

Methods

adjoin	Add additional elements to the end of the Matrix along an axis.
adjoin_trait	Add additional elements to the end of the Matrix along the trait axis.
append	Append values to the matrix.
append_trait	Append values to the Matrix along the trait axis.
concat	Concatenate matrices together along an axis.
concat_trait	Concatenate list of Matrix together along the trait axis.
copy	Make a shallow copy of the Matrix.
deepcopy	Make a deep copy of the Matrix.
delete	Delete sub-arrays along an axis.
delete_trait	Delete sub-arrays along the trait axis.
from_hdf5	Read a DenseTraitMatrix from an HDF5 file.
incorp	Incorporate values along the given axis before the given indices.
incorp_trait	Incorporate values along the trait axis before the given indices.
insert	Insert values along the given axis before the given indices.
insert_trait	Insert values along the trait axis before the given indices.
lexsort	Perform an indirect stable sort using a tuple of keys.
lexsort_trait	Perform an indirect stable sort using a sequence of keys along the trait axis.
remove	Remove sub-arrays along an axis.
remove_trait	Remove sub-arrays along the trait axis.
reorder	Reorder the VariantMatrix.
reorder_trait	Reorder elements of the Matrix along the trait axis using an array of indices.
select	Select certain values from the matrix.
select_trait	Select certain values from the Matrix along the trait axis.
sort	Reset metadata for corresponding axis: name, stix, spix, len.
sort_trait	Sort slements of the Matrix along the trait axis using a sequence of keys.
to_hdf5	Write DenseTraitMatrix to an HDF5 file.

Attributes

mat	Pointer to raw numpy.ndarray object.
mat_ndim	Number of dimensions of the raw numpy.ndarray.
mat_shape	Shape of the raw numpy.ndarray.
ntrait	Number of traits.
trait	Trait label.
trait_axis	Axis along which traits are stored.

__add__(value)

Elementwise add matrices

Parameters:

value (object) – Object which to add.

Returns:

out – An object resulting from the addition.

Return type:

object

__mul__(value)

Elementwise multiply matrices

Parameters:

value (object) – Object which to multiply.

Returns:

out – An object resulting from the multiplication.

Return type:

object

adjoin(values, axis=-1, trait=None, **kwargs)

Add additional elements to the end of the Matrix along an axis.

Parameters:

• values (Matrix, numpy.ndarray) – Values to be adjoined to the Matrix.

• axis (int) – The axis along which values are adjoined.

• trait (numpy.ndarray) – Trait names to adjoin to the Matrix. If values is a DenseTraitMatrix that has a non-None trait field, providing this argument overwrites the field.

• kwargs (dict) – Additional keyword arguments.

Returns:

out – A copy of mat with values adjoined to axis. Note that adjoin does not occur in-place: a new Matrix is allocated and filled.

Return type:

DenseTraitMatrix

adjoin_trait(values, trait=None, **kwargs)

Add additional elements to the end of the Matrix along the trait axis.

Parameters:

• values (DenseTraitMatrix, numpy.ndarray) – Values to be adjoined to the Matrix.

• trait (numpy.ndarray) – Trait names to adjoin to the Matrix. If values is a DenseTraitMatrix that has a non-None trait field, providing this argument overwrites the field.

• kwargs (dict) – Additional keyword arguments.

Returns:

out – A copy of mat with values adjoined to axis. Note that adjoin does not occur in-place: a new Matrix is allocated and filled.

Return type:

DenseTraitMatrix

append(values, axis=-1, trait=None, **kwargs)

Append values to the matrix.

Parameters:

• values (DenseTraitMatrix, numpy.ndarray) – Values are appended to append to the matrix. Must be of type int8. Must be of shape (m, n, p)

• axis (int) – The axis along which values are appended.

• trait (numpy.ndarray) – Trait names to append to the Matrix. If values is a DenseTraitMatrix that has a non-None trait field, providing this argument overwrites the field.

• kwargs (dict) – Additional keyword arguments.

Return type:

None

append_trait(values, trait=None, **kwargs)

Append values to the Matrix along the trait axis.

Parameters:

• values (Matrix, numpy.ndarray) – Values are appended to append to the matrix.

• trait (numpy.ndarray) – Trait names to append to the Matrix.

• kwargs (dict) – Additional keyword arguments.

Return type:

None

classmethod concat(mats, axis=-1, **kwargs)

Concatenate matrices together along an axis.

Parameters:

• mats (Sequence of matrices) – List of Matrix to concatenate. The matrices must have the same shape, except in the dimension corresponding to axis.

• axis (int) – The axis along which the arrays will be joined.

• kwargs (dict) – Additional keyword arguments

Returns:

out – The concatenated matrix. Note that concat does not occur in-place: a new Matrix is allocated and filled.

Return type:

DenseTraitMatrix

classmethod concat_trait(mats, **kwargs)

Concatenate list of Matrix together along the trait axis.

Parameters:

• mats (Sequence of DenseTraitMatrix) – List of DenseTraitMatrix to concatenate. The matrices must have the same shape, except in the dimension corresponding to axis.

• kwargs (dict) – Additional keyword arguments

Returns:

out – The concatenated DenseTraitMatrix. Note that concat does not occur in-place: a new DenseTraitMatrix is allocated and filled.

Return type:

DenseTraitMatrix

copy()

Make a shallow copy of the Matrix.

Returns:

out – A shallow copy of the original DenseMatrix.

Return type:

DenseMatrix

deepcopy(memo=None)

Make a deep copy of the Matrix.

Parameters:

memo (dict) – Dictionary of memo metadata.

Returns:

out – A deep copy of the original DenseMatrix.

Return type:

DenseMatrix

delete(obj, axis=-1, **kwargs)

Delete sub-arrays along an axis.

Parameters:

• obj (int, slice, or Sequence of ints) – Indicate indices of sub-arrays to remove along the specified axis.

• axis (int) – The axis along which to delete the subarray defined by obj.

• kwargs (dict) – Additional keyword arguments.

Returns:

out – A Matrix with deleted elements. Note that concat does not occur in-place: a new Matrix is allocated and filled.

Return type:

DenseTraitMatrix

delete_trait(obj, **kwargs)

Delete sub-arrays along the trait axis.

Parameters:

• obj (int, slice, or Sequence of ints) – Indicate indices of sub-arrays to remove along the specified axis.

• kwargs (dict) – Additional keyword arguments.

Returns:

out – A Matrix with deleted elements. Note that concat does not occur in-place: a new Matrix is allocated and filled.

Return type:

DenseTraitMatrix

classmethod from_hdf5(filename, groupname=None)

Read a DenseTraitMatrix from an HDF5 file.

Parameters:

• filename (str, Path, h5py.File) – If str or Path, an HDF5 file name from which to read. File is closed after reading. If h5py.File, an opened HDF5 file from which to read. File is not closed after reading.

• groupname (str, None) – If str, an HDF5 group name under which DenseTraitMatrix data is stored. If None, DenseTraitMatrix is read from base HDF5 group.

Returns:

out – A dense trait matrix read from file.

Return type:

DenseTraitMatrix

incorp(obj, values, axis=-1, trait=None, **kwargs)

Incorporate values along the given axis before the given indices.

Parameters:

• obj (int, slice, or Sequence of ints) – Object that defines the index or indices before which values is incorporated.

• values (array_like) – Values to incorporate into the matrix.

• axis (int) – The axis along which values are incorporated.

• kwargs (dict) – Additional keyword arguments.

Return type:

None

incorp_trait(obj, values, trait=None, **kwargs)

Incorporate values along the trait axis before the given indices.

Parameters:

• obj (int, slice, or Sequence of ints) – Object that defines the index or indices before which values is incorporated.

• values (Matrix, numpy.ndarray) – Values to incorporate into the matrix.

• trait (numpy.ndarray) – Trait names to incorporate into the Matrix.

• kwargs (dict) – Additional keyword arguments.

Return type:

None

insert(obj, values, axis=-1, trait=None, **kwargs)

Insert values along the given axis before the given indices.

Parameters:

• obj (int, slice, or Sequence of ints) – Object that defines the index or indices before which values is inserted.

• values (DenseTraitMatrix, numpy.ndarray) – Values to insert into the matrix.

• axis (int) – The axis along which values are inserted.

• trait (numpy.ndarray) – Trait names to insert into the Matrix. If values is a DenseTraitMatrix that has a non-None trait field, providing this argument overwrites the field.

• kwargs (dict) – Additional keyword arguments.

Returns:

out – A Matrix with values inserted. Note that insert does not occur in-place: a new Matrix is allocated and filled.

Return type:

DenseTraitMatrix

insert_trait(obj, values, trait=None, **kwargs)

Insert values along the trait axis before the given indices.

Parameters:

• obj (int, slice, or Sequence of ints) – Object that defines the index or indices before which values is inserted.

• values (Matrix, numpy.ndarray) – Values to insert into the matrix.

• trait (numpy.ndarray) – Trait names to insert into the Matrix.

• kwargs (dict) – Additional keyword arguments.

Returns:

out – A Matrix with values inserted. Note that insert does not occur in-place: a new Matrix is allocated and filled.

Return type:

DenseTraitMatrix

lexsort(keys, axis=-1, **kwargs)

Perform an indirect stable sort using a tuple of keys.

Parameters:

• keys (tuple, None) – A tuple of columns to be sorted. The last column is the primary sort key.

• axis (int) – The axis of the Matrix over which to sort values.

Returns:

indices – Array of indices that sort the keys.

Return type:

numpy.ndarray

lexsort_trait(keys=None, **kwargs)

Perform an indirect stable sort using a sequence of keys along the trait axis.

Parameters:

• keys (A (k, N) array or tuple containing k (N,)-shaped sequences) – The k different columns to be sorted. The last column (or row if keys is a 2D array) is the primary sort key.

• kwargs (dict) – Additional keyword arguments.

Returns:

indices – Array of indices that sort the keys along the specified axis.

Return type:

A (N,) ndarray of ints

property mat: ndarray

Pointer to raw numpy.ndarray object.

property mat_ndim: int

Number of dimensions of the raw numpy.ndarray.

property mat_shape: tuple

Shape of the raw numpy.ndarray.

property ntrait: int

Number of traits.

remove(obj, axis=-1, **kwargs)

Remove sub-arrays along an axis.

Parameters:

• obj (int, slice, or Sequence of ints) – Indicate indices of sub-arrays to remove along the specified axis.

• axis (int) – The axis along which to remove the subarray defined by obj.

• kwargs (dict) – Additional keyword arguments.

Return type:

None

remove_trait(obj, **kwargs)

Remove sub-arrays along the trait axis.

Parameters:

• obj (int, slice, or Sequence of ints) – Indicate indices of sub-arrays to remove along the specified axis.

• kwargs (dict) – Additional keyword arguments.

Return type:

None

reorder(indices, axis=-1, **kwargs)

Reorder the VariantMatrix.

Parameters:

• indices (numpy.ndarray) – Indices of where to place elements.

• axis (int) – The axis over which to reorder values.

Return type:

None

reorder_trait(indices, **kwargs)

Reorder elements of the Matrix along the trait axis using an array of indices. Note this modifies the Matrix in-place.

Parameters:

• indices (A (N,) ndarray of ints) – Array of indices that reorder the matrix along the specified axis.

• kwargs (dict) – Additional keyword arguments.

Return type:

None

select(indices, axis=-1, **kwargs)

Select certain values from the matrix.

Parameters:

• indices (array_like (Nj, ...)) – The indices of the values to select.

• axis (int) – The axis along which values are selected.

• kwargs (dict) – Additional keyword arguments.

Returns:

out – The output matrix with values selected. Note that select does not occur in-place: a new Matrix is allocated and filled.

Return type:

DenseTraitMatrix

select_trait(indices, **kwargs)

Select certain values from the Matrix along the trait axis.

Parameters:

• indices (array_like (Nj, ...)) – The indices of the values to select.

• kwargs (dict) – Additional keyword arguments.

Returns:

out – The output Matrix with values selected. Note that select does not occur in-place: a new Matrix is allocated and filled.

Return type:

DenseTraitMatrix

sort(keys, axis=-1, **kwargs)

Reset metadata for corresponding axis: name, stix, spix, len. Sort the VariantMatrix using a tuple of keys.

Parameters:

• keys (tuple, None) – A tuple of columns to be sorted. The last column is the primary sort key.

• axis (int) – The axis over which to sort values.

Return type:

None

sort_trait(keys=None, **kwargs)

Sort slements of the Matrix along the trait axis using a sequence of keys. Note this modifies the Matrix in-place.

Parameters:

• keys (A (k, N) array or tuple containing k (N,)-shaped sequences) – The k different columns to be sorted. The last column (or row if keys is a 2D array) is the primary sort key.

• kwargs (dict) – Additional keyword arguments.

Return type:

None

to_hdf5(filename, groupname=None, overwrite=True)

Write DenseTraitMatrix to an HDF5 file.

Parameters:

• filename (str, Path, h5py.File) – If str, an HDF5 file name to which to write. File is closed after writing. If h5py.File, an opened HDF5 file to which to write. File is not closed after writing.

• groupname (str, None) – If str, an HDF5 group name under which the DenseMatrix data is stored. If None, the DenseMatrix is written to the base HDF5 group.

• overwrite (bool) – Whether to overwrite values in an HDF5 file if a field already exists.

Return type:

None

property trait: ndarray | None

Trait label.

property trait_axis: int

Axis along which traits are stored.