DenseVanRadenCoancestryMatrix#

class pybrops.popgen.cmat.DenseVanRadenCoancestryMatrix.DenseVanRadenCoancestryMatrix(mat, taxa=None, taxa_grp=None, **kwargs)[source]#

Bases: DenseCoancestryMatrix

A concrete class for a dense coancestry matrix calculated using the VanRaden method. Coancestry matrices are square.

The purpose of this concrete class is to implement functionality for:
  1. Dense coancestry matrix value calculation.

  2. Dense coancestry matrix value access.

Constructor for the concrete class DenseVanRadenCoancestryMatrix.

Parameters:
  • mat (numpy.ndarray) – Array from which to construct genomic relationship matrix

  • taxa (numpy.ndarray, None, default = None) – Names of taxa.

  • taxa_grp (numpy.ndarray, None, default = None) – Taxa group assignments.

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

append

Append values to the matrix.

append_taxa

Append values to the Matrix along the taxa axis.

apply_jitter

Add a random jitter value to the diagonal of the coancestry matrix until all eigenvalues exceed the provided eigenvalue tolerance.

coancestry

Retrieve the coancestry between individuals.

concat

Concatenate matrices together along an axis.

concat_taxa

Concatenate list of Matrix together along the taxa axis.

copy

Make a shallow copy of the Matrix.

deepcopy

Make a deep copy of the Matrix.

delete

Delete sub-arrays along an axis.

delete_taxa

Delete sub-arrays along the taxa axis.

from_csv

Read a DenseCoancestryMatrix from a CSV file.

from_gmat

Create a DenseVanRadenCoancestryMatrix from a GenotypeMatrix

from_hdf5

Read a DenseCoancestryMatrix from an HDF5 file.

from_pandas

Read a DenseCoancestryMatrix from a pandas.DataFrame.

group

Sort matrix along axis, then populate grouping indices for the axis.

group_taxa

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

incorp

Incorporate values along the given axis before the given indices.

incorp_taxa

Incorporate values along the taxa axis before the given indices.

insert

Insert values along the given axis before the given indices.

insert_taxa

Insert values along the taxa axis before the given indices.

inverse

Calculate the inverse of the coancestry matrix.

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_positive_semidefinite

Determine whether the coancestry matrix is positive semidefinite.

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.

kinship

Retrieve the kinship between individuals.

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.

mat_asformat

Get matrix in a specific format.

max

Calculate the maximum coancestry or kinship for the CoancestryMatrix along a specified axis.

max_inbreeding

Calculate the maximum attainable inbreeding after one generation for the coancestry matrix.

mean

Calculate the mean coancestry or kinship for the CoancestryMatrix.

min

Calculate the minimum coancestry or kinship for the CoancestryMatrix along a specified axis.

min_inbreeding

Calculate the minimum attainable inbreeding after one generation for the coancestry matrix.

remove

Remove sub-arrays along an axis.

remove_taxa

Remove sub-arrays along the taxa axis.

reorder

Reorder the VariantMatrix.

reorder_taxa

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

select

Select certain values from the matrix.

select_taxa

Select certain values from the Matrix along the taxa axis.

sort

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.

to_csv

Write an object to a CSV file.

to_hdf5

Write DenseCoancestryMatrix to an HDF5 file.

to_pandas

Export a DenseCoancestryMatrix 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

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.

nsquare

Number of axes that are square.

nsquare_taxa

Number of taxa axes that are square.

ntaxa

Number of taxa

square_axes

Axis indices for axes that are square.

square_axes_len

Axis lengths for axes that are square.

square_taxa_axes

Axis indices for taxa axes that are square.

square_taxa_axes_len

Axis lengths for axes that are square.

taxa

Taxa label 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.

__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, **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 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_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

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

Append values to the matrix.

Parameters:
  • values (DenseSquareTaxaMatrix, 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 DenseSquareTaxaMatrix 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 DenseSquareTaxaMatrix 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

apply_jitter(eigvaltol=2e-14, minjitter=1e-10, maxjitter=1e-06, nattempt=100)#

Add a random jitter value to the diagonal of the coancestry matrix until all eigenvalues exceed the provided eigenvalue tolerance. This ensures that a matrix can be decomposed using the Cholesky decomposition. This routine attempts to apply a jitter 100 times before giving up.

Parameters:
  • eigvaltol (float) – Eigenvalue tolerance for determining positive semidefiniteness. If provided eigenvalue tolerance is less than zero, the tolerance is set to 0.0.

  • minjitter (float) – Minimum jitter value applied to a diagonal element.

  • maxjitter (float) – Maximum jitter value applied to a diagonal element.

  • nattempt (int) – Number of jitter application attempts.

Returns:

out – Whether the jitter was successfully applied.

Return type:

bool

coancestry(*args, **kwargs)#

Retrieve the coancestry between individuals.

Parameters:
  • args (tuple) – A tuple of matrix indices to access the coancestry.

  • kwargs (dict) – Additional keyword arguments.

Returns:

out – The coancestry between individuals.

Return type:

Real

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

Return type:

DenseSquareTaxaMatrix

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

copy()#

Make a shallow copy of the Matrix.

Returns:

out – A shallow copy of the original DenseMatrix.

Return type:

DenseMatrix

deepcopy(memo=None)#

Make a deep copy of the Matrix.

Parameters:

memo (dict) – Dictionary of memo metadata.

Returns:

out – A deep copy of the original DenseMatrix.

Return type:

DenseMatrix

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

Delete sub-arrays along an axis.

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

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

  • kwargs (dict) – Additional keyword arguments.

Returns:

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

Return type:

DenseSquareTaxaMatrix

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

classmethod from_csv(filename, sep=',', header=0, taxa_col='taxa', taxa_grp_col='taxa_grp', taxa='all', **kwargs)#

Read a DenseCoancestryMatrix 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.

  • taxa_col (str, Integral, None, default = "taxa") – Name of the column from which to read taxa names. Cannot be None. This column is used to search for column names to extract coancestry values. Elements in this column are interpreted as strings. 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.

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

  • taxa (str, Sequence, default = "all") – Name(s) of the taxa columns for which to read coancestry values. If Sequence, read the taxa names given by the string or integer value in the taxa Sequence. If str, must be equal to "all". Import all taxa names as defined in the taxa_col column.

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

Returns:

out – A DenseCoancestryMatrix read from a CSV file.

Return type:

DenseCoancestryMatrix

classmethod from_gmat(gmat, p_anc=None, **kwargs)[source]#

Create a DenseVanRadenCoancestryMatrix from a GenotypeMatrix

Parameters:
  • gmat (GenotypeMatrix) – Input genotype matrix from which to calculate the genomic relationship matrix.

  • p_anc (numpy.ndarray, Real, None, default = None) – Ancestral allele frequencies. If numpy.ndarray, the array must be of shape (p,) where p is the number of marker loci. If Real, ancestral allele frequencies are assumed constant p_anc across all marker loci. If None, ancestral allele frequencies are estimated from gmat.

Returns:

out – Dense VanRaden genomic relationship matrix.

Return type:

DenseVanRadenCoancestryMatrix

classmethod from_hdf5(filename, groupname=None)#

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

Returns:

out – A DenseCoancestryMatrix read from file.

Return type:

DenseCoancestryMatrix

classmethod from_pandas(df, taxa_col='taxa', taxa_grp_col='taxa_grp', taxa='all', **kwargs)#

Read a DenseCoancestryMatrix from a pandas.DataFrame.

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

  • taxa_col (str, Integral, None, default = "taxa") – Name of the column from which to read taxa names. Cannot be None. This column is used to search for column names to extract coancestry values. Elements in this column are interpreted as strings. 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.

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

  • taxa (str, Sequence, default = "all") – Name(s) of the taxa columns for which to read coancestry values. If Sequence, read the taxa names given by the string or integer value in the taxa Sequence. If str, must be equal to "all". Import all taxa names as defined in the taxa_col column.

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

Returns:

out – A DenseCoancestryMatrix read from a pandas.DataFrame.

Return type:

DenseCoancestryMatrix

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

Sort matrix along axis, then populate grouping indices for the axis.

Parameters:
  • axis (int) – The axis along which values should be 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, **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 corporate into 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 incorporate into 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.

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

insert(obj, values, axis=-1, taxa=None, taxa_grp=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 DenseSquareTaxaMatrix 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 DenseSquareTaxaMatrix that has a non-None taxa_grp field, providing this argument overwrites the field.

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

inverse(format='coancestry')#

Calculate the inverse of the coancestry matrix.

Parameters:

format (str) – Desired matrix type on which to calculate the inverse. Options are “coancestry”, “kinship”.

Returns:

out – Inverse of the coancestry or kinship matrix.

Return type:

numpy.ndarray

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

is_positive_semidefinite(eigvaltol=2e-14)#

Determine whether the coancestry matrix is positive semidefinite.

Parameters:

eigvaltol (Real) – Eigenvalue tolerance for determining positive semidefiniteness. If provided eigenvalue tolerance is less than zero, the tolerance is set to 0.0.

Returns:

out – Whether the coancestry matrix is positive semidefinite.

Return type:

bool

is_square()#

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

Returns:

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

Return type:

bool

is_square_taxa()#

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

Returns:

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

Return type:

bool

kinship(*args, **kwargs)#

Retrieve the kinship between individuals.

Parameters:
  • args (tuple) – A tuple of matrix indices to access the kinship.

  • kwargs (dict) – Additional keyword arguments.

Returns:

out – The kinship between individuals.

Return type:

Real

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

property mat: ndarray#

Pointer to raw numpy.ndarray object.

mat_asformat(format)#

Get matrix in a specific format.

Parameters:

format (str) – Desired output format. Options are “coancestry”, “kinship”.

Returns:

out – Matrix in the desired output format.

Return type:

numpy.ndarray

property mat_ndim: int#

Number of dimensions of the raw numpy.ndarray.

property mat_shape: tuple#

Shape of the raw numpy.ndarray.

max(format='coancestry', axis=None)#

Calculate the maximum coancestry or kinship for the CoancestryMatrix along a specified axis.

Parameters:
  • format (str) – Desired output format. Options are “coancestry”, “kinship”.

  • axis (int, tuple of ints, None) – Axis along which to find the maximum value.

Returns:

out – Maximum coancestry or kinship for the CoancestryMatrix along the specified axis.

Return type:

Real, numpy.ndarray

max_inbreeding(format='coancestry')#

Calculate the maximum attainable inbreeding after one generation for the coancestry matrix. For coancestry, this is equivalent to:

..math:

max(mathrm{diag}(mathbf{G}))

or for kinship, the equivalent is:

..math:

max(mathrm{diag}(mathbf{K}))

Parameters:

format (str) – Desired output format. Options are “coancestry”, “kinship”.

Returns:

out – The maximum attainable inbreeding after one generation.

Return type:

Real

mean(format='coancestry', axis=None, dtype=None)#

Calculate the mean coancestry or kinship for the CoancestryMatrix.

Parameters:
  • format (str) – Desired output format. Options are “coancestry”, “kinship”.

  • axis (int, tuple of ints, None) – Axis along which to find the mean value.

  • dtype (DTypeLike, None) – Type to use in computing the mean. If None use the native float type.

Returns:

out – Mean coancestry or kinship for the CoancestryMatrix.

Return type:

Real

min(format='coancestry', axis=None)#

Calculate the minimum coancestry or kinship for the CoancestryMatrix along a specified axis.

Parameters:
  • format (str) – Desired output format. Options are “coancestry”, “kinship”.

  • axis (int, tuple of ints, None) – Axis along which to find the minimum value.

Returns:

out – Minimum coancestry or kinship for the CoancestryMatrix along the specified axis.

Return type:

Real, numpy.ndarray

min_inbreeding(format='coancestry')#

Calculate the minimum attainable inbreeding after one generation for the coancestry matrix. For coancestry, this is equivalent to:

..math:

frac{1}{mathbf{1’G1}}

or for kinship, the equivalent is:

..math:

frac{1}{mathbf{1’K1}}

Parameters:

format (str) – Desired output format. Options are “coancestry”, “kinship”.

Returns:

out – The minimum attainable inbreeding after one generation.

Return type:

Real

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

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

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

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

Return type:

DenseSquareTaxaMatrix

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

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

property square_axes: tuple#

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, taxa_col='taxa', taxa_grp_col='taxa_grp', taxa='all', sep=',', header=True, index=False, **kwargs)#

Write an object to a CSV file.

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

  • taxa_col (str, default = "taxa") – Name of the column to which to write taxa names. Cannot be None.

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

  • taxa (str, Sequence, default = "all") – Name(s) of the taxa columns for which to write coancestry values. If Sequence, export the taxa names given by the string or integer value in the taxa Sequence. If str, must be equal to "all". Export all taxa names as is.

  • 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 DenseCoancestryMatrix to an HDF5 file.

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

  • groupname (str, None) – If str, an HDF5 group name under which the DenseCoancestryMatrix data is stored. If None, the DenseCoancestryMatrix 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', taxa='all', **kwargs)#

Export a DenseCoancestryMatrix to a pandas.DataFrame.

Parameters:
  • taxa_col (str, default = "taxa") – Name of the column to which to write taxa names. Cannot be None.

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

  • taxa (str, Sequence, default = "all") – Name(s) of the taxa columns for which to write coancestry values. If Sequence, export the taxa names given by the string or integer value in the taxa Sequence. If str, must be equal to "all". Export all taxa names as is.

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

Returns:

out – An output dataframe.

Return type:

pandas.DataFrame

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