DenseBreedingValueMatrix#

class pybrops.popgen.bvmat.DenseBreedingValueMatrix.DenseBreedingValueMatrix(mat, location=0.0, scale=1.0, taxa=None, taxa_grp=None, trait=None, **kwargs)[source]#

Bases: DenseTaxaTraitMatrix, BreedingValueMatrix

The DenseBreedingValueMatrix class uses a dense matrix to represent a Multivariate Breeding Value.

Notes

All elements within a BreedingValueMatrix are mean-centered and scaled to unit variance for each trait.

\[BV = \frac{X - \mu}{\sigma}\]

Where:

\(BV\) is the breeding value.
\(X\) is the phenotype value.
\(\mu\) is the mean (location) for \(X\).
\(\sigma\) is the standard deviation (scale) for \(X\).

Phenotype values can be reconstituted using:

\[X = \sigma BV + \mu\]

BreedingValueMatrix constructor

Parameters:

mat (numpy.ndarray) – An array of breeding values of shape (n,t). It is the responsibility of the user to ensure that the means and standard deviations of this array along the taxa axis are 0 and 1, respectively, if the breeding values are with respect to the individuals in the breeding value matrix.
location (numpy.ndarray, Real) – A numpy.ndarray of shape (t,) containing breeding value locations. If given a Real, create a numpy.ndarray of shape (t,) filled with the provided value.
scale (numpy.ndarray, Real) – A numpy.ndarray of shape (t,) containing breeding value scales. If given a Real, create a numpy.ndarray of shape (t,) filled with the provided value.
taxa (numpy.ndarray, None) – A numpy.ndarray of shape (n,) containing taxa names. If None, do not store any taxa name information.
taxa_grp (numpy.ndarray, None) – A numpy.ndarray of shape (n,) containing taxa groupings. If None, do not store any taxa group information.
trait (numpy.ndarray, None) – A numpy.ndarray of shape (t,) containing trait names. If None, do not store any trait name information.
kwargs (dict) – Used for cooperative inheritance. Dictionary passing unused arguments to the parent class constructor.

Methods

`adjoin`	Add additional elements to the end of the Matrix along an axis.
`adjoin_taxa`	Add additional elements to the end of the TaxaMatrix along the taxa axis.
`adjoin_trait`	Add additional elements to the end of the Matrix along the trait axis.
`append`	Append values to the matrix.
`append_taxa`	Append values to the Matrix along the taxa axis.
`append_trait`	Append values to the Matrix along the trait axis.
`concat`	Concatenate matrices together along an axis.
`concat_taxa`	Concatenate list of Matrix together along the taxa axis.
`concat_trait`	Concatenate list of Matrix 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_taxa`	Delete sub-arrays along the taxa axis.
`delete_trait`	Delete sub-arrays along the variant axis.
`from_csv`	Read a DenseBreedingValueMatrix from a CSV file.
`from_hdf5`	Read `DenseBreedingValueMatrix` from an HDF5 file.
`from_numpy`	Construct a DenseBreedingValueMatrix from a numpy.ndarray.
`from_pandas`	Read a DenseBreedingValueMatrix from a pandas.DataFrame.
`group`	Sort the DenseTaxaTraitMatrix 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.
`incorp_trait`	Incorporate values along the trait 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.
`insert_trait`	Insert values along the variant 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.
`lexsort`	Perform an indirect stable sort using a tuple of keys.
`lexsort_taxa`	Perform an indirect stable sort using a sequence of keys along the taxa axis.
`lexsort_trait`	Perform an indirect stable sort using a sequence of keys along the trait axis.
`remove`	Remove sub-arrays along an axis.
`remove_taxa`	Remove sub-arrays along the taxa axis.
`remove_trait`	Remove sub-arrays along the trait axis.
`reorder`	Reorder the VariantMatrix.
`reorder_taxa`	Reorder elements of the Matrix along the taxa axis using an array of indices.
`reorder_trait`	Reorder elements of the Matrix along the trait 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.
`select_trait`	Select certain values from the Matrix along the variant axis.
`sort`	Reset metadata for corresponding axis: name, stix, spix, len.
`sort_taxa`	Sort slements of the Matrix along the taxa axis using a sequence of keys.
`sort_trait`	Sort slements of the Matrix along the trait axis using a sequence of keys.
`targmax`	Return indices of the maximum values for each trait column (along the taxa axis).
`targmin`	Return indices of the minimum values for each trait column (along the taxa axis).
`tmax`	Return the maximum for each trait column (along the taxa axis).
`tmean`	Return the mean for each trait column (along the taxa axis).
`tmin`	Return the minimum for each trait column (along the taxa axis).
`to_csv`	Write a DenseBreedingValueMatrix to a CSV file.
`to_hdf5`	Write `DenseBreedingValueMatrix` to an HDF5 file.
`to_pandas`	Export a DenseBreedingValueMatrix to a pandas.DataFrame.
`trange`	Return the range for each trait column (along the taxa axis).
`tstd`	Return the standard deviation for each trait column (along the taxa axis).
`tvar`	Return the variance for each trait column (along the taxa axis).
`ungroup`	Ungroup the DenseTaxaTraitMatrix along an axis by removing grouping metadata.
`ungroup_taxa`	Ungroup the DenseTaxaMatrix along the taxa axis by removing taxa group metadata.
`unscale`	Transform values within the BreedingValueMatrix back to their unscaled and de-centered values

Attributes

`location`	Mean of the phenotype values used to calculate breeding values.
`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.
`ntaxa`	Number of taxa
`ntrait`	Number of traits.
`scale`	Standard deviation of the phenotype values used to calculate breeding values.
`taxa`	Taxa label array
`taxa_axis`	Get taxa axis number
`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.
`trait`	Trait label.
`trait_axis`	Get variant axis

__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, taxa=None, taxa_grp=None, trait=None, **kwargs)#

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

Parameters:

values (DenseTaxaTraitMatrix, numpy.ndarray) – Values are appended to append to the Matrix.
axis (int) – The axis along which values are adjoined.
taxa (numpy.ndarray) – Taxa names to adjoin to the Matrix. If values is a DenseTaxaTraitMatrix that has a non-None taxa field, providing this argument overwrites the field.
taxa_grp (numpy.ndarray) – Taxa groups to adjoin to the Matrix. If values is a DenseTaxaTraitMatrix that has a non-None taxa_grp field, providing this argument overwrites the field.
trait (numpy.ndarray) – Traits to adjoin to the Matrix. If values is a DenseTaxaTraitMatrix 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 appended to axis. Note that adjoin does not occur in-place: a new Matrix is allocated and filled.

Return type:

DenseTaxaTraitMatrix

adjoin_taxa(values, taxa=None, taxa_grp=None, **kwargs)[source]#

Add additional elements to the end of the TaxaMatrix along the taxa axis. Copy-on-manipulation routine.

Parameters:

values (BreedingValueMatrix, numpy.ndarray) – Values to be appended to append to the Matrix. If numpy.ndarray, assumed to be unscaled.
taxa (numpy.ndarray) – Taxa names to adjoin to the Matrix. If values is a DenseBreedingValueMatrix that has a non-None taxa field, providing this argument overwrites the field.
taxa_grp (numpy.ndarray) – Taxa groups to adjoin to the Matrix. If values is a DenseBreedingValueMatrix that has a non-None taxa_grp field, providing this argument overwrites the field.
kwargs (dict) – Additional keyword arguments.

Returns:

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

Return type:

DenseBreedingValueMatrix

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

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

Parameters:

values (DenseTaxaTraitMatrix, numpy.ndarray) – Values to be adjoined to the Matrix.
trait (numpy.ndarray) – Trait names to adjoin to the Matrix. If values is a DenseTaxaTraitMatrix 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:

DenseTaxaTraitMatrix

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

Append values to the matrix.

Parameters:

values (DenseTaxaTraitMatrix, 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.
taxa (numpy.ndarray) – Taxa names to append to the Matrix. If values is a DenseTaxaTraitMatrix that has a non-None taxa field, providing this argument overwrites the field.
taxa_grp (numpy.ndarray) – Taxa groups to append to the Matrix. If values is a DenseTaxaTraitMatrix that has a non-None taxa_grp field, providing this argument overwrites the field.
trait (numpy.ndarray) – Trait names to append to the Matrix. If values is a DenseTaxaTraitMatrix that has a non-None trait field, providing this argument overwrites the field.
kwargs (dict) – Additional keyword arguments.

Return type:

None

append_taxa(values, taxa=None, taxa_grp=None, **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

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:

DenseTaxaTraitMatrix

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 DenseTaxaTraitMatrix. Note that concat does not occur in-place: a new DenseTaxaTraitMatrix is allocated and filled.

Return type:

DenseTaxaTraitMatrix

classmethod concat_trait(mats, **kwargs)#

Concatenate list of Matrix together along the variant 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 DenseTaxaTraitMatrix. Note that concat does not occur in-place: a new DenseTaxaTraitMatrix is allocated and filled.

Return type:

DenseTaxaTraitMatrix

copy()[source]#

Make a shallow copy of the Matrix.

Returns:: out – A shallow copy of the original DenseMatrix.
Return type:: DenseMatrix

deepcopy(memo=None)[source]#

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 DenseTaxaTraitMatrix with deleted elements. Note that concat does not occur in-place: a new DenseTaxaTraitMatrix is allocated and filled.

Return type:

DenseTaxaTraitMatrix

delete_taxa(obj, **kwargs)[source]#

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 DenseBreedingValueMatrix with deleted elements. Note that concat does not occur in-place: a new DenseBreedingValueMatrix is allocated and filled.

Return type:

DenseBreedingValueMatrix

delete_trait(obj, **kwargs)#

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 DenseTaxaTraitMatrix with deleted elements. Note that concat does not occur in-place: a new DenseTaxaTraitMatrix is allocated and filled.

Return type:

DenseTaxaTraitMatrix

classmethod from_csv(filename, location=0.0, scale=1.0, taxa_col='taxa', taxa_grp_col='taxa_grp', trait_cols='infer', sep=',', header=0, **kwargs)[source]#

Read a DenseBreedingValueMatrix from a CSV file.

Parameters:

filename (str) – CSV file name from which to read.
sep (str, default = ',') – CSV delimiter to use.
header (int, list of int, default=0) – Row number(s) to use as the column names, and the start of the data.
location (numpy.ndarray, Real, default = 0.0) – A numpy.ndarray of shape (t,) containing breeding value locations. If given a Real, create a numpy.ndarray of shape (t,) filled with the provided value.
scale (numpy.ndarray, Real, default = 1.0) – A numpy.ndarray of shape (t,) containing breeding value scales. If given a Real, create a numpy.ndarray of shape (t,) filled with the provided value.
taxa_col (str, Integral, None, default = "taxa") – Name of the column from which to read taxa names. If of type str, taxa names are read from the column named defined by taxa_col. If of type Integral, taxa names are read from the column number defined by taxa_col. If None, taxa names are not imported.
taxa_grp_col (str, None, default = "taxa_grp") – Name of the column from which to read taxa group names. If of type str, taxa group names are read from the column named defined by taxa_col. If of type Integral, taxa group names are read from the column number defined by taxa_col. If None, taxa group names are not imported.
trait_cols (Sequence, str, None, default = "trait") – Names of the trait columns to which to read breeding values. If Sequence, column names are given by the strings or integers in the trait_cols Sequence. If str, must be equal to "infer". Use remaining columns in the input dataframe to load trait breeding values. If None, do not load any trait breeding values.
kwargs (dict) – Additional keyword arguments to use for dictating importing from a CSV.

Returns:

out – A DenseBreedingValueMatrix read from a CSV file.

Return type:

DenseBreedingValueMatrix

classmethod from_hdf5(filename, groupname=None)[source]#

Read DenseBreedingValueMatrix 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 DenseBreedingValueMatrix data is stored. If None, DenseBreedingValueMatrix is read from base HDF5 group.

Returns:

gmat – A DenseBreedingValueMatrix read from file.

Return type:

DenseBreedingValueMatrix

classmethod from_numpy(mat, taxa=None, taxa_grp=None, trait=None, **kwargs)[source]#

Construct a DenseBreedingValueMatrix from a numpy.ndarray. Calculates mean-centering and scaling to unit variance.

Parameters:

mat (numpy.ndarray) –
A float64 matrix of shape (n,t).

Where:
- n is the number of taxa.
- t is the number of traits.
taxa (numpy.ndarray) – An array of taxa names.
taxa_grp (numpy.ndarray) – An array of taxa groups.
trait (numpy.ndarray) – An array of trait names.

Returns:

out – Output breeding value matrix.

Return type:

DenseBreedingValueMatrix

classmethod from_pandas(df, location=0.0, scale=1.0, taxa_col='taxa', taxa_grp_col='taxa_grp', trait_cols='infer', **kwargs)[source]#

Read a DenseBreedingValueMatrix from a pandas.DataFrame.

Parameters:

df (pandas.DataFrame) – Pandas dataframe from which to read.
location (numpy.ndarray, Real, default = 0.0) – A numpy.ndarray of shape (t,) containing breeding value locations. If given a Real, create a numpy.ndarray of shape (t,) filled with the provided value.
scale (numpy.ndarray, Real, default = 1.0) – A numpy.ndarray of shape (t,) containing breeding value scales. If given a Real, create a numpy.ndarray of shape (t,) filled with the provided value.
taxa_col (str, Integral, None, default = "taxa") – Name of the column from which to read taxa names. If of type str, taxa names are read from the column named defined by taxa_col. If of type Integral, taxa names are read from the column number defined by taxa_col. If None, taxa names are not imported.
taxa_grp_col (str, None, default = "taxa_grp") – Name of the column to which to read taxa group names. If of type str, taxa group names are read from the column named defined by taxa_col. If of type Integral, taxa group names are read from the column number defined by taxa_col. If None, taxa group names are not imported.
trait_cols (Sequence, str, None, default = "trait") – Names of the trait columns to which to read breeding values. If Sequence, column names are given by the strings or integers in the trait_cols Sequence. If str, must be equal to "infer". Use remaining columns in the input dataframe to load trait breeding values. If None, do not load any trait breeding values.
kwargs (dict) – Additional keyword arguments to use for dictating importing from a pandas.DataFrame.

Returns:

out – A DenseBreedingValueMatrix read from a pandas.DataFrame.

Return type:

DenseBreedingValueMatrix

group(axis=-1, **kwargs)#

Sort the DenseTaxaTraitMatrix 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

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

incorp(obj, values, axis=-1, taxa=None, taxa_grp=None, 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.
taxa (numpy.ndarray) – Taxa names to incorporate into the Matrix. If values is a DenseTaxaTraitMatrix that has a non-None taxa field, providing this argument overwrites the field.
taxa_grp (numpy.ndarray) – Taxa groups to incorporate into the Matrix. If values is a DenseTaxaTraitMatrix that has a non-None taxa_grp field, providing this argument overwrites the field.
trait (numpy.ndarray) – Trait names to incorporate into the Matrix. If values is a DenseTaxaTraitMatrix that has a non-None trait field, providing this argument overwrites the field.
kwargs (dict) – Additional keyword arguments.

Return type:

None

incorp_taxa(obj, values, taxa=None, taxa_grp=None, **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

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, taxa=None, taxa_grp=None, 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 (DenseTaxaTraitMatrix, numpy.ndarray) – Values to insert into the matrix.
axis (int) – The axis along which values are inserted.
taxa (numpy.ndarray) – Taxa names to insert into the Matrix. If values is a DenseTaxaTraitMatrix that has a non-None taxa field, providing this argument overwrites the field.
taxa_grp (numpy.ndarray) – Taxa groups to insert into the Matrix. If values is a DenseTaxaTraitMatrix that has a non-None taxa_grp field, providing this argument overwrites the field.
trait (numpy.ndarray) – Trait names to insert into the Matrix. If values is a DenseTaxaTraitMatrix that has a non-None trait field, providing this argument overwrites the field.
kwargs (dict) – Additional keyword arguments.

Returns:

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

Return type:

DenseTaxaTraitMatrix

insert_taxa(obj, values, taxa=None, taxa_grp=None, **kwargs)[source]#

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 (BreedingValueMatrix, 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 DenseBreedingValueMatrix with values inserted. Note that insert does not occur in-place: a new DenseBreedingValueMatrix is allocated and filled.

Return type:

DenseBreedingValueMatrix

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

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.
trait (numpy.ndarray) – Trait names to insert into the Matrix. If values is a DenseTaxaTraitMatrix that has a non-None trait field, providing this argument overwrites the field.
kwargs (dict) – Additional keyword arguments.

Returns:

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

Return type:

DenseTaxaTraitMatrix

is_grouped(axis=-1, **kwargs)#

Determine whether the Matrix has been sorted and grouped.

Parameters:

axis (int) – Axis along which to test for grouping.
kwargs (dict) – Additional keyword arguments.

Returns:

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

Return type:

bool

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

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. If None, sort using vrnt_chrgrp as primary key, and vrnt_phypos as secondary key.
axis (int) – The axis of the Matrix over which to sort values.
kwargs (dict) – Additional keyword arguments.

Returns:

indices – Array of indices that sort the keys.

Return type:

numpy.ndarray

lexsort_taxa(keys=None, **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

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 location: ndarray#: Mean of the phenotype values used to calculate breeding values.

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 ntaxa: int#: Number of taxa

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_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

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.
kwargs (dict) – Additional keyword arguments.

Return type:

None

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

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

property scale: ndarray#: Standard deviation of the phenotype values used to calculate breeding values.

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 DenseTaxaTraitMatrix with values selected. Note that select does not occur in-place: a new DenseTaxaTraitMatrix is allocated and filled.

Return type:

DenseTaxaTraitMatrix

select_taxa(indices, **kwargs)[source]#

Select certain values from the Matrix along the taxa axis. Selection re-centers and re-scales breeding values to mean zero and unit variance.

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:

Matrix

select_trait(indices, **kwargs)#

Select certain values from the Matrix along the variant axis.

Parameters:

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

Returns:

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

Return type:

DenseTaxaTraitMatrix

sort(keys=None, 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. If None, sort using vrnt_chrgrp as primary key, and vrnt_phypos as secondary key.
axis (int) – The axis over which to sort values.
kwargs (dict) – Additional keyword arguments.

Return type:

None

sort_taxa(keys=None, **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

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

targmax()[source]#

Return indices of the maximum values for each trait column (along the taxa axis).

Returns:

out – An index array of shape (t,) containing indices of maximum values along the taxa axis.

Where:

t is the number of traits.

Return type:

numpy.ndarray

targmin()[source]#

Return indices of the minimum values for each trait column (along the taxa axis).

Returns:

out – An index array of shape (t,) containing indices of minimum values along the taxa axis.

Where:

t is the number of traits.

Return type:

numpy.ndarray

property taxa: ndarray | None#: Taxa label array

property taxa_axis: int#: Get taxa axis number

property taxa_grp: ndarray | None#: Taxa group label.

property taxa_grp_len: ndarray | None#: Taxa group length.

property taxa_grp_name: ndarray | None#: Taxa group name.

property taxa_grp_spix: ndarray | None#: Taxa group stop index.

property taxa_grp_stix: ndarray | None#: Taxa group start index.

tmax(unscale=False)[source]#

Return the maximum for each trait column (along the taxa axis).

Parameters:

unscale (bool, default = False) – Whether to transform results to their unscaled values.

Returns:

out – An array of shape (t,) containing maximum values along the taxa axis.

Where:

t is the number of traits.

Return type:

numpy.ndarray

tmean(unscale=False)[source]#

Return the mean for each trait column (along the taxa axis).

Parameters:

unscale (bool, default = False) – Whether to transform results to their unscaled values.

Returns:

out – An array of shape (t,) containing maximum values along the taxa axis.

Where:

t is the number of traits.

Return type:

numpy.ndarray

tmin(unscale=False)[source]#

Return the minimum for each trait column (along the taxa axis).

Parameters:

unscale (bool, default = False) – Whether to transform results to their unscaled values.

Returns:

out – An index array of shape (t,) containing minimum values along the taxa axis.

Where:

t is the number of traits.

Return type:

numpy.ndarray

to_csv(filename, taxa_col='taxa', taxa_grp_col='taxa_grp', trait_cols='all', unscale=False, sep=',', header=True, index=False, **kwargs)[source]#

Write a DenseBreedingValueMatrix to a CSV file.

Parameters:

filename (str) – CSV file name to which to write.
taxa_col (str, None, default = "taxa") – Name of the column to which to write taxa names. If str, the column is given the name in taxa_col. If None, the column is not exported.
taxa_grp_col (str, None, default = "taxa_grp") – Name of the column to which to write taxa group names. If str, the column is given the name in taxa_grp_col. If None, the column is not exported.
trait_cols (Sequence, str, None, default = "all") – Names of the trait columns to which to write breeding values. If Sequence, column names are given by the strings in the trait_cols Sequence. If str, must be equal to "all". Use trait names given in the trait property. If None, use numeric trait column names.
unscale (bool, default = False) – whether to transform breeding values to their unscaled values.
sep (str, default = ",") – Separator to use in the exported CSV file.
header (bool, default = True) – Whether to save header names.
index (bool, default = False) – Whether to save a row index in the exported CSV file.
kwargs (dict) – Additional keyword arguments to use for dictating export to a CSV.

Return type:

None

to_hdf5(filename, groupname=None, overwrite=True)[source]#

Write DenseBreedingValueMatrix 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 DenseBreedingValueMatrix data is stored. If None, DenseBreedingValueMatrix 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

to_pandas(taxa_col='taxa', taxa_grp_col='taxa_grp', trait_cols='all', unscale=False, **kwargs)[source]#

Export a DenseBreedingValueMatrix to a pandas.DataFrame.

Parameters:

taxa_col (str, None, default = "taxa") – Name of the column to which to write taxa names. If str, the column is given the name in taxa_col. If None, the column is not exported.
taxa_grp_col (str, None, default = "taxa_grp") – Name of the column to which to write taxa group names. If str, the column is given the name in taxa_grp_col. If None, the column is not exported.
trait_cols (Sequence, str, None, default = "trait") – Names of the trait columns to which to write breeding values. If Sequence, column names are given by the strings in the trait_cols Sequence. If str, must be equal to "all". Use all trait names given in the trait property. If None, use numeric trait column names.
unscale (bool, default = False) – whether to transform breeding values to their unscaled values.
kwargs (dict) – Additional keyword arguments to use for dictating export to a pandas.DataFrame.

Returns:

out – An output dataframe.

Return type:

pandas.DataFrame

property trait: ndarray | None#: Trait label.

property trait_axis#: Get variant axis

trange(unscale=False)[source]#

Return the range for each trait column (along the taxa axis).

Parameters:

unscale (bool, default = False) – Whether to transform results to their unscaled values.

Returns:

out – An array of shape (t,) containing range values along the taxa axis.

Where:

t is the number of traits.

Return type:

numpy.ndarray

tstd(unscale=False)[source]#

Return the standard deviation for each trait column (along the taxa axis).

Parameters:

unscale (bool, default = False) – whether to transform results to their unscaled values.

Returns:

out – An array of shape (t,) containing standard deviation values along the taxa axis.

Where:

t is the number of traits.

Return type:

numpy.ndarray

tvar(unscale=False)[source]#

Return the variance for each trait column (along the taxa axis).

Parameters:

unscale (bool, default = False) – whether to transform results to their unscaled values.

Returns:

out – An array of shape (t,) containing variance values along the taxa axis.

Where:

t is the number of traits.

Return type:

numpy.ndarray

ungroup(axis=-1, **kwargs)#

Ungroup the DenseTaxaTraitMatrix 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

ungroup_taxa(**kwargs)#

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

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

unscale()[source]#

Transform values within the BreedingValueMatrix back to their unscaled and de-centered values

Returns:

out – An array of shape (n,t) containing unscaled and de-centered values.

Where:

n is the number of taxa.
t is the number of traits.

Return type:

numpy.ndarray