VariantMatrix#

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

Bases: GroupableMatrix

An abstract class for matrix wrapper objects with variant metadata.

The purpose of this abstract class is to provide base functionality for:

variant metadata manipulation routines.
variant manipulation routines.

Methods

`adjoin`	Add additional elements to the end of the Matrix along an axis.
`adjoin_vrnt`	Add additional elements to the end of the VariantMatrix along the variant axis.
`append`	Append values to the Matrix.
`append_vrnt`	Append values to the VariantMatrix along the variant axis.
`concat`	Concatenate matrices together along an axis.
`concat_vrnt`	Concatenate list of VariantMatrix together along the variant 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_vrnt`	Delete sub-arrays along the variant axis.
`from_hdf5`	Read an object from an HDF5 file.
`group`	Sort the GroupableMatrix along an axis, then populate grouping indices.
`group_vrnt`	Sort the VariantMatrix along the variant axis, then populate grouping indices for the variant axis.
`incorp`	Incorporate values along the given axis before the given indices.
`incorp_vrnt`	Incorporate values along the variant axis before the given indices.
`insert`	Insert values along the given axis before the given indices.
`insert_vrnt`	Insert values along the variant axis before the given indices.
`is_grouped`	Determine whether the Matrix has been sorted and grouped.
`is_grouped_vrnt`	Determine whether the Matrix has been sorted and grouped along the variant axis.
`lexsort`	Perform an indirect stable sort using a sequence of keys.
`lexsort_vrnt`	Perform an indirect stable sort using a sequence of keys along the variant axis.
`remove`	Remove sub-arrays along an axis.
`remove_vrnt`	Remove sub-arrays along the variant axis.
`reorder`	Reorder elements of the Matrix using an array of indices.
`reorder_vrnt`	Reorder elements of the Matrix along the variant axis using an array of indices.
`select`	Select certain values from the matrix.
`select_vrnt`	Select certain values from the VariantMatrix along the variant axis.
`sort`	Sort slements of the Matrix using a sequence of keys.
`sort_vrnt`	Sort slements of the Matrix along the variant 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_vrnt`	Ungroup the VariantMatrix along the variant axis by removing variant 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.
`nvrnt`	Number of variants.
`vrnt_axis`	Axis along which variants are stored.
`vrnt_chrgrp`	Variant chromosome group label.
`vrnt_chrgrp_len`	Variant chromosome group length.
`vrnt_chrgrp_name`	Variant chromosome group names.
`vrnt_chrgrp_spix`	Variant chromosome group stop indices.
`vrnt_chrgrp_stix`	Variant chromosome group start indices.
`vrnt_genpos`	Variant genetic position.
`vrnt_hapalt`	Variant haplotype sequence.
`vrnt_hapgrp`	Variant haplotype group label.
`vrnt_hapref`	Variant reference haplotype sequence.
`vrnt_mask`	Variant mask.
`vrnt_name`	Variant name.
`vrnt_phypos`	Variant physical position.
`vrnt_xoprob`	Variant crossover sequential probability.

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_vrnt(values, vrnt_chrgrp, vrnt_phypos, vrnt_name, vrnt_genpos, vrnt_xoprob, vrnt_hapgrp, vrnt_mask, **kwargs)[source]#

Add additional elements to the end of the VariantMatrix along the variant axis.

Parameters:

values (Matrix, numpy.ndarray) – Values are appended to adjoin to the Matrix.
vrnt_chrgrp (numpy.ndarray) – Variant chromosome groups to adjoin to the Matrix.
vrnt_phypos (numpy.ndarray) – Variant chromosome physical positions to adjoin to the Matrix.
vrnt_name (numpy.ndarray) – Variant names to adjoin to the Matrix.
vrnt_genpos (numpy.ndarray) – Variant chromosome genetic positions to adjoin to the Matrix.
vrnt_xoprob (numpy.ndarray) – Sequential variant crossover probabilities to adjoin to the Matrix.
vrnt_hapgrp (numpy.ndarray) – Variant haplotype labels to adjoin to the Matrix.
vrnt_mask (numpy.ndarray) – Variant mask to adjoin to the Matrix.
kwargs (dict) – Additional keyword arguments.

Returns:

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

Return type:

VariantMatrix

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_vrnt(values, vrnt_chrgrp, vrnt_phypos, vrnt_name, vrnt_genpos, vrnt_xoprob, vrnt_hapgrp, vrnt_mask, **kwargs)[source]#

Append values to the VariantMatrix along the variant axis.

Parameters:

values (Matrix, numpy.ndarray) – Values are appended to append to the VariantMatrix.
vrnt_chrgrp (numpy.ndarray) – Variant chromosome groups to append to the VariantMatrix.
vrnt_phypos (numpy.ndarray) – Variant chromosome physical positions to append to the VariantMatrix.
vrnt_name (numpy.ndarray) – Variant names to append to the VariantMatrix.
vrnt_genpos (numpy.ndarray) – Variant chromosome genetic positions to append to the VariantMatrix.
vrnt_xoprob (numpy.ndarray) – Sequential variant crossover probabilities to append to the VariantMatrix.
vrnt_hapgrp (numpy.ndarray) – Variant haplotype labels to append to the VariantMatrix.
vrnt_mask (numpy.ndarray) – Variant mask to append to the VariantMatrix.
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_vrnt(mats, **kwargs)[source]#

Concatenate list of VariantMatrix together along the variant axis.

Parameters:

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

Return type:

VariantMatrix

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_vrnt(obj, **kwargs)[source]#

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

Return type:

VariantMatrix

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_vrnt(**kwargs)[source]#

Sort the VariantMatrix along the variant axis, then populate grouping indices for the variant 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_vrnt(obj, values, vrnt_chrgrp, vrnt_phypos, vrnt_name, vrnt_genpos, vrnt_xoprob, vrnt_hapgrp, vrnt_mask, **kwargs)[source]#

Incorporate values along the variant 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 VariantMatrix.
vrnt_chrgrp (numpy.ndarray) – Variant chromosome groups to incorporate into the VariantMatrix.
vrnt_phypos (numpy.ndarray) – Variant chromosome physical positions to incorporate into the VariantMatrix.
vrnt_name (numpy.ndarray) – Variant names to incorporate into the VariantMatrix.
vrnt_genpos (numpy.ndarray) – Variant chromosome genetic positions to incorporate into the VariantMatrix.
vrnt_xoprob (numpy.ndarray) – Sequential variant crossover probabilities to incorporate into the VariantMatrix.
vrnt_hapgrp (numpy.ndarray) – Variant haplotype labels to incorporate into the VariantMatrix.
vrnt_mask (numpy.ndarray) – Variant mask to incorporate into the VariantMatrix.
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_vrnt(obj, values, vrnt_chrgrp, vrnt_phypos, vrnt_name, vrnt_genpos, vrnt_xoprob, vrnt_hapgrp, vrnt_mask, **kwargs)[source]#

Insert values along the variant 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 (array_like) – Values to insert into the matrix.
vrnt_chrgrp (numpy.ndarray) – Variant chromosome groups to insert into the Matrix.
vrnt_phypos (numpy.ndarray) – Variant chromosome physical positions to insert into the Matrix.
vrnt_name (numpy.ndarray) – Variant names to insert into the Matrix.
vrnt_genpos (numpy.ndarray) – Variant chromosome genetic positions to insert into the Matrix.
vrnt_xoprob (numpy.ndarray) – Sequential variant crossover probabilities to insert into the Matrix.
vrnt_hapgrp (numpy.ndarray) – Variant haplotype labels to insert into the Matrix.
vrnt_mask (numpy.ndarray) – Variant mask to insert into the Matrix.
kwargs (dict) – Additional keyword arguments.

Returns:

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

Return type:

VariantMatrix

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_vrnt(**kwargs)[source]#

Determine whether the Matrix has been sorted and grouped along the variant 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 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_vrnt(keys, **kwargs)[source]#

Perform an indirect stable sort using a sequence of keys along the variant 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 nvrnt: int#: Number of variants.

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_vrnt(obj, **kwargs)[source]#

Remove sub-arrays along the variant 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_vrnt(indices, **kwargs)[source]#

Reorder elements of the Matrix along the variant axis 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.
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_vrnt(indices, **kwargs)[source]#

Select certain values from the VariantMatrix along the variant axis.

Parameters:

indices (ArrayLike (Nj, ...)) – The indices of the values to select.
kwargs (dict) – Additional keyword arguments.

Returns:

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

Return type:

VariantMatrix

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_vrnt(keys, **kwargs)[source]#

Sort slements of the Matrix along the variant 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 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_vrnt(**kwargs)[source]#

Ungroup the VariantMatrix along the variant axis by removing variant group metadata.

Parameters:: kwargs (dict) – Additional keyword arguments.
Return type:: None

abstract property vrnt_axis: int#: Axis along which variants are stored.

abstract property vrnt_chrgrp: object#: Variant chromosome group label.

abstract property vrnt_chrgrp_len: object#: Variant chromosome group length.

abstract property vrnt_chrgrp_name: object#: Variant chromosome group names.

abstract property vrnt_chrgrp_spix: object#: Variant chromosome group stop indices.

abstract property vrnt_chrgrp_stix: object#: Variant chromosome group start indices.

abstract property vrnt_genpos: object#: Variant genetic position.

abstract property vrnt_hapalt: object#: Variant haplotype sequence.

abstract property vrnt_hapgrp: object#: Variant haplotype group label.

abstract property vrnt_hapref: object#: Variant reference haplotype sequence.

abstract property vrnt_mask: object#: Variant mask.

abstract property vrnt_name: object#: Variant name.

abstract property vrnt_phypos: object#: Variant physical position.

abstract property vrnt_xoprob: object#: Variant crossover sequential probability.