DenseThreeWayDHAdditiveGeneticVarianceMatrix

class pybrops.model.vmat.DenseThreeWayDHAdditiveGeneticVarianceMatrix.DenseThreeWayDHAdditiveGeneticVarianceMatrix(mat, taxa=None, taxa_grp=None, trait=None, **kwargs)

Bases: DenseAdditiveGeneticVarianceMatrix

A concrete class for dense additive genetic variance matrices calculated for three-way DH progenies.

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

1. Genetic variance estimation for three-way DH progenies.

2. I/O for three-way DH progeny variance matrices.

Constructor for the concrete class DenseThreeWayDHAdditiveGeneticVarianceMatrix.

Parameters:

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

• taxa (numpy.ndarray) – Taxa names.

• taxa_grp (numpy.ndarray) – Taxa groupings.

• trait (numpy.ndarray) – Trait names.

• kwargs (dict) – Additional keyword arguments.

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 an 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 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_taxa	Delete sub-arrays along the taxa axis.
delete_trait	Delete sub-arrays along the trait axis.
from_algmod	Calculate a symmetrical tensor of progeny variances for each possible 3-way cross between inbred individuals.
from_csv	Read an object from a CSV file.
from_gmod	Calculate a symmetrical tensor of progeny variances for each possible 3-way cross between inbred individuals.
from_hdf5	Read DenseThreeWayDHAdditiveGeneticVarianceMatrix from an HDF5 file.
from_pandas	Read a DenseThreeWayDHAdditiveGeneticVarianceMatrix from a pandas.DataFrame.
group	Sort the DenseSquareTaxaTraitMatrix 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 trait 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 axis 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 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 trait 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.
to_csv	Write a DenseThreeWayDHAdditiveGeneticVarianceMatrix to a CSV file.
to_hdf5	Write DenseThreeWayDHAdditiveGeneticVarianceMatrix to an HDF5 file.
to_pandas	Export a DenseThreeWayDHAdditiveGeneticVarianceMatrix to a pandas.DataFrame.
ungroup	Ungroup the DenseSquareTaxaMatrix along an axis by removing grouping metadata.
ungroup_taxa	Ungroup the DenseTaxaMatrix along the taxa axis by removing taxa group metadata.

Attributes

epgc	Get a tuple of the expected parental genome contributions.
female_axis	Axis along which female parents are stored.
male_axis	Axis along which male parents are stored.
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.
nfemale	Number of female parents.
nmale	Number of male parents.
nrecurrent	Number of recurrent parents.
nsquare	Number of axes that are square.
nsquare_taxa	Number of taxa axes that are square.
ntaxa	Number of taxa
ntrait	Number of traits.
recurrent_axis	Axis along which recurrent parents are stored.
square_axes	Get 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 array
taxa_axis	First square 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.
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, taxa=None, taxa_grp=None, trait=None, **kwargs)

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

Parameters:

• values (Matrix, 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 DenseSquareTaxaTraitMatrix 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 DenseSquareTaxaTraitMatrix that has a non-None taxa_grp field, providing this argument overwrites the field.

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

• kwargs (dict) – Additional keyword arguments.

Returns:

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

Return type:

DenseSquareTaxaTraitMatrix

adjoin_taxa(values, taxa=None, taxa_grp=None, **kwargs)

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

Parameters:

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

• taxa (numpy.ndarray) – Taxa names to adjoin to the Matrix. If values is a DenseSquareTaxaMatrix 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 DenseSquareTaxaMatrix that has a non-None taxa_grp field, providing this argument overwrites the field.

• kwargs (dict) – Additional keyword arguments.

Returns:

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

Return type:

DenseSquareTaxaMatrix

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

Append values to the matrix.

Parameters:

• values (DenseSquareTaxaTraitMatrix, 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 DenseSquareTaxaTraitMatrix 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 DenseSquareTaxaTraitMatrix that has a non-None taxa_grp field, providing this argument overwrites the field.

• trait (numpy.ndarray, None) – Trait names to append to the Matrix. If values is a DenseSquareTaxaTraitMatrix that has a non-None taxa_grp 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 DenseSquareTaxaTraitMatrix. Note that concat does not occur in-place: a new DenseSquareTaxaTraitMatrix is allocated and filled.

Return type:

DenseSquareTaxaTraitMatrix

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

Return type:

DenseSquareTaxaMatrix

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 DenseGeneticVarianceMatrix.

Return type:

DenseGeneticVarianceMatrix

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 DenseGeneticVarianceMatrix.

Return type:

DenseGeneticVarianceMatrix

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

Return type:

DenseSquareTaxaTraitMatrix

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

Return type:

DenseSquareTaxaMatrix

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

property epgc: tuple

Get a tuple of the expected parental genome contributions.

property female_axis: Integral

Axis along which female parents are stored.

classmethod from_algmod(algmod, pgmat, nmating, nprogeny, nself, gmapfn, mem=1024)

Calculate a symmetrical tensor of progeny variances for each possible 3-way cross between inbred individuals. Calculations are derived from Lehermeier et al. (2019).

Parameters:

• algmod (AdditiveLinearGenomicModel) – AdditiveLinearGenomicModel with which to estimate genetic variances.

• pgmat (PhasedGenotypeMatrix) – Input genomes to use to estimate genetic variances.

• nmating (Integral) – Number of cross patterns to simulate for genetic variance estimation.

• nprogeny (Integral) – Number of progeny to simulate per cross to estimate genetic variance.

• nself (Integral, Real) –

  Number of selfing generations post-cross pattern before ‘nprogeny’ individuals are simulated.

  Example	Description
  nself = 0	Derive gametes from F1
  nself = 1	Derive gametes from F2
  nself = 2	Derive gametes from F3
  ...	etc.
  nself = inf	Derive gametes from SSD

• gmapfn (GeneticMapFunction) – GeneticMapFunction to use to estimate covariance induced by recombination.

• mem (Integral, default = 1024) –

  Memory chunk size to use during matrix operations. If None, then memory chunk size is not limited.

  WARNING: Setting mem = None might result in memory allocation errors! For reference, mem = 1024 refers to a matrix of size 1024x1024, which needs about 8.5 MB of storage. Matrices of course need a quadratic amount of memory: \(O(n^2)\).

Returns:

out – A matrix of additive genetic variance estimations.

Return type:

GeneticVarianceMatrix

classmethod from_csv(filename, recurrent_col='recurrent', recurrent_grp_col='recurrent_grp', female_col='female', female_grp_col='female_grp', male_col='male', male_grp_col='male_grp', trait_col='trait', variance_col='variance', sep=',', header=0, **kwargs)

Read an object from a CSV file.

Parameters:

• filename (str) – CSV file name from which to read.

• recurrent_col (str, Integral, default = "recurrent") – Name or index of the column from which to read recurrent taxa names.

• recurrent_grp_col (str, Integral, None, default = "recurrent") – Name or index of the column from which to read recurrent taxa groups.

• female_col (str, Integral, default = "female") – Name or index of the column from which to read female taxa names.

• female_grp_col (str, Integral, None, default = "female") – Name or index of the column from which to read female taxa groups.

• male_col (str, Integral, None, default = "male") – Name or index of the column from which to read male taxa names.

• male_grp_col (str, Integral, None, default = "male") – Name or index of the column from which to read male taxa names.

• trait_col (str, Integral, default = "trait") – Name or index of the column from which to read trait taxa names.

• variance_col (str, Integral, default = "variance") – Name or index of the column from which to read variance taxa names.

• sep (str, default = ",") – Separator to use in the CSV file.

• header (int, default = 0) – Row index of the header.

• kwargs (dict) – Additional keyword arguments to use for dictating importing from a CSV.

Returns:

out – An object read from a CSV file.

Return type:

CSVInputOutput

classmethod from_gmod(gmod, pgmat, nmating, nprogeny, nself, gmapfn, **kwargs)

Calculate a symmetrical tensor of progeny variances for each possible 3-way cross between inbred individuals.

Parameters:

• gmod (GenomicModel) – Genomic Model with which to estimate genetic variances.

• pgmat (PhasedGenotypeMatrix) – Input genomes to use to estimate genetic variances.

• nmating (Integral) – Number of cross patterns to simulate for genetic variance estimation.

• nprogeny (Integral) – Number of progeny to simulate per cross to estimate genetic variance.

• nself (Integral, Real) –

  Number of selfing generations post-cross pattern before ‘nprogeny’ individuals are simulated.

  Example	Description
  nself = 0	Derive gametes from F1
  nself = 1	Derive gametes from F2
  nself = 2	Derive gametes from F3
  ...	etc.
  nself = inf	Derive gametes from SSD

• gmapfn (GeneticMapFunction) – GeneticMapFunction to use to estimate covariance induced by recombination.

• kwargs (dict) – Additional keyword arguments.

Returns:

out – A matrix of additive genetic variance estimations.

Return type:

DenseThreeWayDHAdditiveGeneticVarianceMatrix

classmethod from_hdf5(filename, groupname=None)

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

Returns:

out – A DenseThreeWayDHAdditiveGeneticVarianceMatrix read from file.

Return type:

DenseThreeWayDHAdditiveGeneticVarianceMatrix

classmethod from_pandas(df, recurrent_col='recurrent', recurrent_grp_col='recurrent_grp', female_col='female', female_grp_col='female_grp', male_col='male', male_grp_col='male_grp', trait_col='trait', variance_col='variance', **kwargs)

Read a DenseThreeWayDHAdditiveGeneticVarianceMatrix from a pandas.DataFrame.

Parameters:

• df (pandas.DataFrame) – Pandas dataframe from which to read.

• recurrent_col (str, Integral, default = "recurrent") – Name or index of the column from which to read recurrent taxa names.

• recurrent_grp_col (str, Integral, None, default = "recurrent") – Name or index of the column from which to read recurrent taxa groups.

• female_col (str, Integral, default = "female") – Name or index of the column from which to read female taxa names.

• female_grp_col (str, Integral, None, default = "female") – Name or index of the column from which to read female taxa groups.

• male_col (str, Integral, None, default = "male") – Name or index of the column from which to read male taxa names.

• male_grp_col (str, Integral, None, default = "male") – Name or index of the column from which to read male taxa names.

• trait_col (str, Integral, default = "trait") – Name or index of the column from which to read trait taxa names.

• variance_col (str, Integral, default = "variance") – Name or index of the column from which to read variance taxa names.

• kwargs (dict) – Additional keyword arguments to use for dictating importing from a pandas.DataFrame.

Returns:

out – A DenseThreeWayDHAdditiveGeneticVarianceMatrix read from a pandas.DataFrame.

Return type:

DenseThreeWayDHAdditiveGeneticVarianceMatrix

group(axis=-1, **kwargs)

Sort the DenseSquareTaxaTraitMatrix 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 DenseSquareTaxaTraitMatrix 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 DenseSquareTaxaTraitMatrix that has a non-None taxa_grp field, providing this argument overwrites the field.

• trait (numpy.ndarray, None) – Trait names to incorporate into the Matrix. If values is a DenseSquareTaxaTraitMatrix that has a non-None taxa_grp 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 (Matrix, 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 DenseSquareTaxaTraitMatrix 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 DenseSquareTaxaTraitMatrix that has a non-None taxa_grp field, providing this argument overwrites the field.

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

• kwargs (dict) – Additional keyword arguments.

Returns:

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

Return type:

DenseSquareTaxaTraitMatrix

insert_taxa(obj, values, taxa=None, taxa_grp=None, **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 DenseSquareTaxaMatrix with values inserted. Note that insert does not occur in-place: a new DenseSquareTaxaMatrix is allocated and filled.

Return type:

DenseSquareTaxaMatrix

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

is_grouped(axis=-1, **kwargs)

Determine whether the Matrix has been sorted and grouped.

Parameters:

• axis (int) – Axis 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

is_square()

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

Returns:

out – True if all square axes are the same length. False if not all square axes are the same length.

Return type:

bool

is_square_taxa()

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

Returns:

out – True if all square taxa axes are the same length. False if not all square taxa axes are the same length.

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.

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

Axis along which male parents are stored.

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 nfemale: Integral

Number of female parents.

property nmale: Integral

Number of male parents.

property nrecurrent: Integral

Number of recurrent parents.

property nsquare: int

Number of axes that are square.

property nsquare_taxa: int

Number of taxa axes that are square.

property ntaxa: int

Number of taxa

property ntrait: int

Number of traits.

property recurrent_axis: Integral

Axis along which recurrent parents are stored.

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

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

Return type:

DenseSquareTaxaTraitMatrix

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

Return type:

DenseSquareTaxaMatrix

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=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.

• 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

property square_axes: tuple

Get axis indices for axes that are square

property square_axes_len: tuple

Axis lengths for axes that are square.

property square_taxa_axes: tuple

Axis indices for taxa axes that are square.

property square_taxa_axes_len: tuple

Axis lengths for axes that are square.

property taxa: ndarray | None

Taxa label array

property taxa_axis: int

First square axis along which taxa are stored

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.

to_csv(filename, recurrent_col='recurrent', recurrent_grp_col='recurrent_grp', female_col='female', female_grp_col='female_grp', male_col='male', male_grp_col='male_grp', trait_col='trait', variance_col='variance', sep=',', header=True, index=False, **kwargs)

Write a DenseThreeWayDHAdditiveGeneticVarianceMatrix to a CSV file.

Parameters:

• filename (str) – CSV file name to which to write.

• recurrent_col (str, default = "recurrent") – Name of the column to which to write recurrent taxa names.

• recurrent_grp_col (str, None, default = "recurrent_grp") – Name of the column to which to write recurrent taxa groups.

• female_col (str, default = "female") – Name of the column to which to write female taxa names.

• female_grp_col (str, None, default = "female_grp") – Name of the column to which to write female taxa groups.

• male_col (str, default = "male") – Name of the column to which to write male taxa names.

• male_grp_col (str, None, default = "male_grp") – Name of the column to which to write male taxa groups.

• trait_col (str, default = "trait") – Name of the column to which to write trait taxa names.

• variance_col (str, default = "variance") – Name of the column to which to write variance taxa names.

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

Write DenseThreeWayDHAdditiveGeneticVarianceMatrix to an HDF5 file.

Parameters:

• filename (str, Path, h5py.File) – HDF5 file name or HDF5 file stream to which to write.

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

• overwrite (bool) – Whether to overwrite data fields if they are present in the HDF5 file.

Return type:

None

to_pandas(recurrent_col='recurrent', recurrent_grp_col='recurrent_grp', female_col='female', female_grp_col='female_grp', male_col='male', male_grp_col='male_grp', trait_col='trait', variance_col='variance', **kwargs)

Export a DenseThreeWayDHAdditiveGeneticVarianceMatrix to a pandas.DataFrame.

Parameters:

• female_col (str, default = "female") – Name of the column to which to write female taxa names.

• female_grp_col (str, None, default = "female_grp") – Name of the column to which to write female taxa groups.

• male_col (str, default = "male") – Name of the column to which to write male taxa names.

• male_grp_col (str, None, default = "male_grp") – Name of the column to which to write male taxa groups.

• recurrent_col (str, default = "recurrent") – Name of the column to which to write recurrent taxa names.

• recurrent_grp_col (str, None, default = "recurrent_grp") – Name of the column to which to write recurrent taxa groups.

• trait_col (str, default = "trait") – Name of the column to which to write trait taxa names.

• variance_col (str, default = "variance") – Name of the column to which to write variance taxa names.

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

Axis along which traits are stored.

ungroup(axis=-1, **kwargs)

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