SquareTaxaMatrix#

class pybrops.core.mat.SquareTaxaMatrix.SquareTaxaMatrix[source]#

Bases: SquareMatrix, TaxaMatrix

An abstract class for matrix wrapper objects with square taxa metadata.

The purpose of this abstract class is to merge the following interfaces:

  1. SquareMatrix

  2. TaxaMatrix

Methods

adjoin

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

adjoin_taxa

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

append

Append values to the Matrix.

append_taxa

Append values to the Matrix along the taxa axis.

concat

Concatenate matrices together along an axis.

concat_taxa

Concatenate list of Matrix together along the taxa 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_taxa

Delete sub-arrays along the taxa axis.

from_hdf5

Read an object from an HDF5 file.

group

Sort the GroupableMatrix along an axis, then populate grouping indices.

group_taxa

Sort the Matrix along the taxa axis, then populate grouping indices for the taxa axis.

incorp

Incorporate values along the given axis before the given indices.

incorp_taxa

Incorporate values along the taxa axis before the given indices.

insert

Insert values along the given axis before the given indices.

insert_taxa

Insert values along the taxa axis before the given indices.

is_grouped

Determine whether the Matrix has been sorted and grouped.

is_grouped_taxa

Determine whether the Matrix has been sorted and grouped along the taxa axis.

is_square

Determine whether the axes lengths for the square axes are identical.

is_square_taxa

Determine whether the taxa axes lengths for the square axes are identical.

lexsort

Perform an indirect stable sort using a sequence of keys.

lexsort_taxa

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

remove

Remove sub-arrays along an axis.

remove_taxa

Remove sub-arrays along the taxa axis.

reorder

Reorder elements of the Matrix using an array of indices.

reorder_taxa

Reorder elements of the Matrix along the taxa axis using an array of indices.

select

Select certain values from the matrix.

select_taxa

Select certain values from the Matrix along the taxa axis.

sort

Sort slements of the Matrix using a sequence of keys.

sort_taxa

Sort slements of the Matrix along the taxa axis using a sequence of keys.

to_hdf5

Write an object to an HDF5 file.

ungroup

Ungroup the GroupableMatrix along an axis by removing grouping metadata.

ungroup_taxa

Ungroup the TaxaMatrix along the taxa axis by removing taxa group metadata.

Attributes

mat

Pointer to raw matrix object.

mat_ndim

Number of dimensions of the raw matrix.

mat_shape

Shape of the raw matrix.

nsquare

Number of axes that are square.

nsquare_taxa

Number of taxa axes that are square.

ntaxa

Number of taxa.

square_axes

Axis indices for axes that are square.

square_axes_len

Axis lengths for axes that are square.

square_taxa_axes

Axis indices for taxa axes that are square.

square_taxa_axes_len

Axis lengths for axes that are square.

taxa

Taxa label.

taxa_axis

Axis along which taxa are stored.

taxa_grp

Taxa group label.

taxa_grp_len

Taxa group length.

taxa_grp_name

Taxa group name.

taxa_grp_spix

Taxa group stop index.

taxa_grp_stix

Taxa group start index.

abstract __add__(value)#

Elementwise add matrices

Parameters:

value (object) – Object which to add.

Returns:

out – An object resulting from the addition.

Return type:

object

abstract __mul__(value)#

Elementwise multiply matrices

Parameters:

value (object) – Object which to multiply.

Returns:

out – An object resulting from the multiplication.

Return type:

object

abstract adjoin(values, axis, **kwargs)#

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

Parameters:
  • values (Matrix or numpy.ndarray) – Values are appended to append to the Matrix.

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

  • kwargs (dict) – Additional keyword arguments.

Returns:

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

Return type:

Matrix

abstract adjoin_taxa(values, taxa, taxa_grp, **kwargs)#

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

Parameters:
  • values (Matrix, numpy.ndarray) – Values are appended to adjoin to the Matrix.

  • taxa (numpy.ndarray) – Taxa names to adjoin to the Matrix.

  • taxa_grp (numpy.ndarray) – Taxa groups to adjoin to the Matrix.

  • kwargs (dict) – Additional keyword arguments.

Returns:

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

Return type:

TaxaMatrix

abstract append(values, axis, **kwargs)#

Append values to the Matrix.

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

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

  • kwargs (dict) – Additional keyword arguments.

Return type:

None

abstract append_taxa(values, taxa, taxa_grp, **kwargs)#

Append values to the Matrix along the taxa axis.

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

  • taxa (numpy.ndarray) – Taxa names to append to the Matrix.

  • taxa_grp (numpy.ndarray) – Taxa groups to append to the Matrix.

  • kwargs (dict) – Additional keyword arguments.

Return type:

None

abstract classmethod concat(mats, axis, **kwargs)#

Concatenate matrices together along an axis.

Parameters:
  • mats (Sequence of Matrix) – 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:

Matrix

abstract classmethod concat_taxa(mats, **kwargs)#

Concatenate list of Matrix together along the taxa axis.

Parameters:
  • mats (Sequence of Matrix) – List of Matrix 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 TaxaMatrix. Note that concat does not occur in-place: a new TaxaMatrix is allocated and filled.

Return type:

TaxaMatrix

abstract copy()#

Make a shallow copy of the Matrix.

Returns:

out – A shallow copy of the original Matrix.

Return type:

Matrix

abstract deepcopy(memo)#

Make a deep copy of the Matrix.

Parameters:

memo (dict) – Dictionary of memo metadata.

Returns:

out – A deep copy of the original Matrix.

Return type:

Matrix

abstract delete(obj, axis, **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:

Matrix

abstract delete_taxa(obj, **kwargs)#

Delete sub-arrays along the taxa 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 TaxaMatrix with deleted elements. Note that concat does not occur in-place: a new TaxaMatrix is allocated and filled.

Return type:

TaxaMatrix

abstract classmethod from_hdf5(filename, groupname)#

Read an object from an HDF5 file.

Parameters:
  • filename (str, Path, h5py.File) – If str, an HDF5 file name from which to read. If Path, an HDF5 file name from which to read. If h5py.File, an opened HDF5 file from which to read.

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

Returns:

out – An object read from an HDF5 file.

Return type:

HDF5InputOutput

abstract group(axis, **kwargs)#

Sort the GroupableMatrix along an axis, then populate grouping indices.

Parameters:
  • axis (int) – The axis along which values are grouped.

  • kwargs (dict) – Additional keyword arguments.

Return type:

None

abstract group_taxa(**kwargs)#

Sort the Matrix along the taxa axis, then populate grouping indices for the taxa axis.

Parameters:

kwargs (dict) – Additional keyword arguments.

Return type:

None

abstract incorp(obj, values, axis, **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 (numpy.ndarray) – Values to incorporate into the matrix.

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

  • kwargs (dict) – Additional keyword arguments.

Return type:

None

abstract incorp_taxa(obj, values, taxa, taxa_grp, **kwargs)#

Incorporate values along the taxa 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.

  • taxa (numpy.ndarray) – Taxa names to incorporate into the Matrix.

  • taxa_grp (numpy.ndarray) – Taxa groups to incorporate into the Matrix.

  • kwargs (dict) – Additional keyword arguments.

Return type:

None

abstract insert(obj, values, axis, **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 (ArrayLike) – Values to insert into the matrix.

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

  • 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:

Matrix

abstract insert_taxa(obj, values, taxa, taxa_grp, **kwargs)#

Insert values along the taxa 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.

  • taxa (numpy.ndarray) – Taxa names to insert into the Matrix.

  • taxa_grp (numpy.ndarray) – Taxa groups to insert into the Matrix.

  • kwargs (dict) – Additional keyword arguments.

Returns:

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

Return type:

TaxaMatrix

abstract is_grouped(axis, **kwargs)#

Determine whether the Matrix has been sorted and grouped.

Parameters:
  • axis (int) – Axis along which to determine whether elements have been sorted and grouped.

  • kwargs (dict) – Additional keyword arguments.

Returns:

grouped – True or False indicating whether the Matrix has been sorted and grouped.

Return type:

bool

abstract is_grouped_taxa(**kwargs)#

Determine whether the Matrix has been sorted and grouped along the taxa axis.

Parameters:

kwargs (dict) – Additional keyword arguments.

Returns:

grouped – True or False indicating whether the Matrix has been sorted and grouped.

Return type:

bool

abstract is_square()#

Determine whether the axes lengths for the square axes are identical.

Returns:

outTrue if all square axes are the same length. False if not all square axes are the same length.

Return type:

bool

abstract is_square_taxa()[source]#

Determine whether the taxa axes lengths for the square axes are identical.

Returns:

outTrue if all square taxa axes are the same length. False if not all square taxa axes are the same length.

Return type:

bool

abstract lexsort(keys, axis, **kwargs)#

Perform an indirect stable sort using a sequence of keys.

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.

  • axis (int) – Axis to be indirectly sorted.

  • 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

abstract lexsort_taxa(keys, **kwargs)#

Perform an indirect stable sort using a sequence of keys along the taxa 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

abstract property mat: object#

Pointer to raw matrix object.

abstract property mat_ndim: int#

Number of dimensions of the raw matrix.

abstract property mat_shape: tuple#

Shape of the raw matrix.

abstract property nsquare: int#

Number of axes that are square.

abstract property nsquare_taxa: int#

Number of taxa axes that are square.

abstract property ntaxa: int#

Number of taxa.

abstract remove(obj, axis, **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

abstract remove_taxa(obj, **kwargs)#

Remove sub-arrays along the taxa 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

abstract reorder(indices, axis, **kwargs)#

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

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

  • axis (int) – Axis to be reordered.

  • kwargs (dict) – Additional keyword arguments.

Return type:

None

abstract reorder_taxa(indices, **kwargs)#

Reorder elements of the Matrix along the taxa 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

abstract select(indices, axis, **kwargs)#

Select certain values from the matrix.

Parameters:
  • indices (ArrayLike (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:

Matrix

abstract select_taxa(indices, **kwargs)#

Select certain values from the Matrix along the taxa axis.

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

  • kwargs (dict) – Additional keyword arguments.

Returns:

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

Return type:

TaxaMatrix

abstract sort(keys, axis, **kwargs)#

Sort slements of the Matrix 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.

  • axis (int) – Axis to be indirectly sorted.

  • kwargs (dict) – Additional keyword arguments.

Return type:

None

abstract sort_taxa(keys, **kwargs)#

Sort slements of the Matrix along the taxa 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

abstract property square_axes: tuple#

Axis indices for axes that are square.

abstract property square_axes_len: tuple#

Axis lengths for axes that are square.

abstract property square_taxa_axes: tuple#

Axis indices for taxa axes that are square.

abstract property square_taxa_axes_len: tuple#

Axis lengths for axes that are square.

abstract property taxa: object#

Taxa label.

abstract property taxa_axis: int#

Axis along which taxa are stored.

abstract property taxa_grp: object#

Taxa group label.

abstract property taxa_grp_len: object#

Taxa group length.

abstract property taxa_grp_name: object#

Taxa group name.

abstract property taxa_grp_spix: object#

Taxa group stop index.

abstract property taxa_grp_stix: object#

Taxa group start index.

abstract to_hdf5(filename, groupname, overwrite)#

Write an object to an HDF5 file.

Parameters:
  • filename (str, Path, h5py.File) – If str, an HDF5 file name to which to write. If Path, an HDF5 file path to which to write. If h5py.File, an opened HDF5 file to which to write.

  • groupname (str, None) – If str, an HDF5 group name under which object data is stored. If None, object 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

abstract ungroup(axis, **kwargs)#

Ungroup the GroupableMatrix along an axis by removing grouping metadata.

Parameters:
  • axis (int) – The axis along which values should be ungrouped.

  • kwargs (dict) – Additional keyword arguments.

Return type:

None

abstract ungroup_taxa(**kwargs)#

Ungroup the TaxaMatrix along the taxa axis by removing taxa group metadata.

Parameters:

kwargs (dict) – Additional keyword arguments.

Return type:

None