CoancestryMatrix#

class pybrops.popgen.cmat.CoancestryMatrix.CoancestryMatrix[source]#

Bases: SquareTaxaMatrix, PandasInputOutput, CSVInputOutput, HDF5InputOutput

An abstract class for coancestry matrices. Coancestry matrices are square. Coancestry matrices are related to kinship matrices in the following manner:

..math:

mathbf{K} = frac{1}{2}mathbf{A}

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

Coancestry matrix value calculation.
Coancestry matrix value access.

Methods

`adjoin`	Add additional elements to the end of the Matrix along an axis.
`adjoin_taxa`	Add additional elements to the end of the Matrix along the taxa axis.
`append`	Append values to the Matrix.
`append_taxa`	Append values to the Matrix along the taxa axis.
`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 `CoancestryMatrix` from a CSV file.
`from_gmat`	Create a CoancestryMatrix from a GenotypeMatrix.
`from_hdf5`	Read a `CoancestryMatrix` from an HDF5 file.
`from_pandas`	Read a `CoancestryMatrix` from a `pandas.DataFrame`.
`group`	Sort the GroupableMatrix along an axis, then populate grouping indices.
`group_taxa`	Sort the Matrix along the taxa axis, then populate grouping indices for the taxa axis.
`incorp`	Incorporate values along the given axis before the given indices.
`incorp_taxa`	Incorporate values along the taxa axis before the given indices.
`insert`	Insert values along the given axis before the given indices.
`insert_taxa`	Insert values along the taxa axis before the given indices.
`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 axes 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 sequence 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 along a specified axis.
`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 elements of the Matrix using an array of indices.
`reorder_taxa`	Reorder elements of the Matrix along the taxa axis using an array of indices.
`select`	Select certain values from the matrix.
`select_taxa`	Select certain values from the Matrix along the taxa axis.
`sort`	Sort slements of the Matrix using a sequence of keys.
`sort_taxa`	Sort slements of the Matrix along the taxa axis using a sequence of keys.
`to_csv`	Write an object to a CSV file.
`to_hdf5`	Write an object to an HDF5 file.
`to_pandas`	Export a `CoancestryMatrix` to a `pandas.DataFrame`.
`ungroup`	Ungroup the GroupableMatrix along an axis by removing grouping metadata.
`ungroup_taxa`	Ungroup the TaxaMatrix along the taxa axis by removing taxa group metadata.

Attributes

`mat`	Pointer to raw matrix object.
`mat_ndim`	Number of dimensions of the raw matrix.
`mat_shape`	Shape of the raw matrix.
`nsquare`	Number of axes that are square.
`nsquare_taxa`	Number of taxa axes that are square.
`ntaxa`	Number of taxa.
`square_axes`	Axis indices for axes that are square.
`square_axes_len`	Axis lengths for axes that are square.
`square_taxa_axes`	Axis indices for taxa axes that are square.
`square_taxa_axes_len`	Axis lengths for axes that are square.
`taxa`	Taxa label.
`taxa_axis`	Axis along which taxa are stored.
`taxa_grp`	Taxa group label.
`taxa_grp_len`	Taxa group length.
`taxa_grp_name`	Taxa group name.
`taxa_grp_spix`	Taxa group stop index.
`taxa_grp_stix`	Taxa group start index.

abstract __add__(value)#

Elementwise add matrices

Parameters:: value (object) – Object which to add.
Returns:: out – An object resulting from the addition.
Return type:: object

abstract __mul__(value)#

Elementwise multiply matrices

Parameters:: value (object) – Object which to multiply.
Returns:: out – An object resulting from the multiplication.
Return type:: object

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

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

Parameters:

values (Matrix or numpy.ndarray) – Values are appended to append to the Matrix.
axis (int) – The axis along which values are adjoined.
kwargs (dict) – Additional keyword arguments.

Returns:

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

Return type:

Matrix

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

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

Parameters:

values (Matrix, numpy.ndarray) – Values are appended to adjoin to the Matrix.
taxa (numpy.ndarray) – Taxa names to adjoin to the Matrix.
taxa_grp (numpy.ndarray) – Taxa groups to adjoin to the Matrix.
kwargs (dict) – Additional keyword arguments.

Returns:

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

Return type:

TaxaMatrix

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

Append values to the Matrix.

Parameters:

values (Matrix, numpy.ndarray) – Values are appended to append to the matrix.
axis (int) – The axis along which values are appended.
kwargs (dict) – Additional keyword arguments.

Return type:

None

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

Append values to the Matrix along the taxa axis.

Parameters:

values (Matrix, numpy.ndarray) – Values are appended to append to the matrix.
taxa (numpy.ndarray) – Taxa names to append to the Matrix.
taxa_grp (numpy.ndarray) – Taxa groups to append to the Matrix.
kwargs (dict) – Additional keyword arguments.

Return type:

None

abstract apply_jitter(eigvaltol, minjitter, maxjitter, nattempt)[source]#

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

abstract coancestry(*args, **kwargs)[source]#

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

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

Concatenate matrices together along an axis.

Parameters:

mats (Sequence of Matrix) – List of Matrix to concatenate. The matrices must have the same shape, except in the dimension corresponding to axis.
axis (int) – The axis along which the arrays will be joined.
kwargs (dict) – Additional keyword arguments

Returns:

out – The concatenated matrix. Note that concat does not occur in-place: a new Matrix is allocated and filled.

Return type:

Matrix

abstract classmethod concat_taxa(mats, **kwargs)#

Concatenate list of Matrix together along the taxa axis.

Parameters:

mats (Sequence of Matrix) – List of Matrix to concatenate. The matrices must have the same shape, except in the dimension corresponding to axis.
kwargs (dict) – Additional keyword arguments

Returns:

out – The concatenated TaxaMatrix. Note that concat does not occur in-place: a new TaxaMatrix is allocated and filled.

Return type:

TaxaMatrix

abstract copy()#

Make a shallow copy of the Matrix.

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

abstract deepcopy(memo)#

Make a deep copy of the Matrix.

Parameters:: memo (dict) – Dictionary of memo metadata.
Returns:: out – A deep copy of the original Matrix.
Return type:: Matrix

abstract delete(obj, axis, **kwargs)#

Delete sub-arrays along an axis.

Parameters:

obj (int, slice, or Sequence of ints) – Indicate indices of sub-arrays to remove along the specified axis.
axis (int) – The axis along which to delete the subarray defined by obj.
kwargs (dict) – Additional keyword arguments.

Returns:

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

Return type:

Matrix

abstract delete_taxa(obj, **kwargs)#

Delete sub-arrays along the taxa axis.

Parameters:

obj (int, slice, or Sequence of ints) – Indicate indices of sub-arrays to remove along the specified axis.
kwargs (dict) – Additional keyword arguments.

Returns:

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

Return type:

TaxaMatrix

abstract classmethod from_csv(filename, **kwargs)[source]#

Read a CoancestryMatrix from a CSV file.

Parameters:

filename (str) – CSV file name from which to read.
kwargs (dict) – Additional keyword arguments to use for dictating importing from a CSV.

Returns:

out – A CoancestryMatrix read from a CSV file.

Return type:

CoancestryMatrix

abstract classmethod from_gmat(gmat, **kwargs)[source]#

Create a CoancestryMatrix from a GenotypeMatrix.

Parameters:

gmat (GenotypeMatrix) – Input genotype matrix from which to calculate coancestry.
kwargs (dict) – Additional keyword arguments.

Returns:

out – A coancestry matrix.

Return type:

CoancestryMatrix

abstract classmethod from_hdf5(filename, groupname)[source]#

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

Returns:

out – A CoancestryMatrix read from an HDF5 file.

Return type:

CoancestryMatrix

abstract classmethod from_pandas(df, **kwargs)[source]#

Read a CoancestryMatrix from a pandas.DataFrame.

Parameters:

df (pandas.DataFrame) – Pandas dataframe from which to read.
kwargs (dict) – Additional keyword arguments to use for dictating importing from a pandas.DataFrame.

Returns:

out – A CoancestryMatrix read from a pandas.DataFrame.

Return type:

PandasInputOutput

abstract group(axis, **kwargs)#

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

Parameters:

axis (int) – The axis along which values are grouped.
kwargs (dict) – Additional keyword arguments.

Return type:

None

abstract group_taxa(**kwargs)#

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

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

abstract incorp(obj, values, axis, **kwargs)#

Incorporate values along the given axis before the given indices.

Parameters:

obj (int, slice, or Sequence of ints) – Object that defines the index or indices before which values is incorporated.
values (numpy.ndarray) – Values to incorporate into the matrix.
axis (int) – The axis along which values are incorporated.
kwargs (dict) – Additional keyword arguments.

Return type:

None

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

Incorporate values along the taxa axis before the given indices.

Parameters:

obj (int, slice, or Sequence of ints) – Object that defines the index or indices before which values is incorporated.
values (Matrix, numpy.ndarray) – Values to incorporate into the matrix.
taxa (numpy.ndarray) – Taxa names to incorporate into the Matrix.
taxa_grp (numpy.ndarray) – Taxa groups to incorporate into the Matrix.
kwargs (dict) – Additional keyword arguments.

Return type:

None

abstract insert(obj, values, axis, **kwargs)#

Insert values along the given axis before the given indices.

Parameters:

obj (int, slice, or Sequence of ints) – Object that defines the index or indices before which values is inserted.
values (ArrayLike) – Values to insert into the matrix.
axis (int) – The axis along which values are inserted.
kwargs (dict) – Additional keyword arguments.

Returns:

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

Return type:

Matrix

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

Insert values along the taxa axis before the given indices.

Parameters:

obj (int, slice, or Sequence of ints) – Object that defines the index or indices before which values is inserted.
values (Matrix, numpy.ndarray) – Values to insert into the matrix.
taxa (numpy.ndarray) – Taxa names to insert into the Matrix.
taxa_grp (numpy.ndarray) – Taxa groups to insert into the Matrix.
kwargs (dict) – Additional keyword arguments.

Returns:

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

Return type:

TaxaMatrix

abstract inverse(format)[source]#

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

abstract is_grouped(axis, **kwargs)#

Determine whether the Matrix has been sorted and grouped.

Parameters:

axis (int) – Axis along which to determine whether elements have been sorted and grouped.
kwargs (dict) – Additional keyword arguments.

Returns:

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

Return type:

bool

abstract is_grouped_taxa(**kwargs)#

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

Parameters:: kwargs (dict) – Additional keyword arguments.
Returns:: grouped – True or False indicating whether the Matrix has been sorted and grouped.
Return type:: bool

abstract is_positive_semidefinite(eigvaltol)[source]#

Determine whether the coancestry matrix is positive semidefinite.

Parameters:: eigvaltol (float) – Eigenvalue tolerance for determining positive semidefiniteness.
Returns:: out – Whether the coancestry matrix is positive semidefinite.
Return type:: bool

abstract is_square()#

Determine whether the axes 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

abstract 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

abstract kinship(*args, **kwargs)[source]#

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

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

Perform an indirect stable sort using a sequence of keys.

Parameters:

keys (A (k, N) array or tuple containing k (N,)-shaped sequences) – The k different columns to be sorted. The last column (or row if keys is a 2D array) is the primary sort key.
axis (int) – Axis to be indirectly sorted.
kwargs (dict) – Additional keyword arguments.

Returns:

indices – Array of indices that sort the keys along the specified axis.

Return type:

A (N,) ndarray of ints

abstract lexsort_taxa(keys, **kwargs)#

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

Parameters:

keys (A (k, N) array or tuple containing k (N,)-shaped sequences) – The k different columns to be sorted. The last column (or row if keys is a 2D array) is the primary sort key.
kwargs (dict) – Additional keyword arguments.

Returns:

indices – Array of indices that sort the keys along the specified axis.

Return type:

A (N,) ndarray of ints

abstract property mat: object#: Pointer to raw matrix object.

abstract mat_asformat(format)[source]#

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

abstract property mat_ndim: int#: Number of dimensions of the raw matrix.

abstract property mat_shape: tuple#: Shape of the raw matrix.

abstract max(format, axis)[source]#

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

abstract max_inbreeding(format)[source]#

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

..math:: max(mathrm{trace}(mathbf{G}))

or for kinship, the equivalent is:

..math:: max(mathrm{trace}(mathbf{K}))

Parameters:: format (str) – Desired output format. Options are “coancestry”, “kinship”.
Returns:: out – The maximum attainable inbreeding after one generation.
Return type:: Real

abstract mean(format, axis, dtype)[source]#

Calculate the mean 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 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 along the specified axis.

Return type:

Real

abstract min(format, axis)[source]#

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

abstract min_inbreeding(format)[source]#

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

abstract property nsquare: int#: Number of axes that are square.

abstract property nsquare_taxa: int#: Number of taxa axes that are square.

abstract property ntaxa: int#: Number of taxa.

abstract remove(obj, axis, **kwargs)#

Remove sub-arrays along an axis.

Parameters:

obj (int, slice, or Sequence of ints) – Indicate indices of sub-arrays to remove along the specified axis.
axis (int) – The axis along which to remove the subarray defined by obj.
kwargs (dict) – Additional keyword arguments.

Return type:

None

abstract remove_taxa(obj, **kwargs)#

Remove sub-arrays along the taxa axis.

Parameters:

obj (int, slice, or Sequence of ints) – Indicate indices of sub-arrays to remove along the specified axis.
kwargs (dict) – Additional keyword arguments.

Return type:

None

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

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

Parameters:

indices (A (N,) ndarray of ints, Sequence of ints) – Array of indices that reorder the matrix along the specified axis.
axis (int) – Axis to be reordered.
kwargs (dict) – Additional keyword arguments.

Return type:

None

abstract reorder_taxa(indices, **kwargs)#

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

Parameters:

indices (A (N,) ndarray of ints) – Array of indices that reorder the matrix along the specified axis.
kwargs (dict) – Additional keyword arguments.

Return type:

None

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

Select certain values from the matrix.

Parameters:

indices (ArrayLike (Nj, ...)) – The indices of the values to select.
axis (int) – The axis along which values are selected.
kwargs (dict) – Additional keyword arguments.

Returns:

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

Return type:

Matrix

abstract select_taxa(indices, **kwargs)#

Select certain values from the Matrix along the taxa axis.

Parameters:

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

Returns:

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

Return type:

TaxaMatrix

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

Sort slements of the Matrix using a sequence of keys. Note this modifies the Matrix in-place.

Parameters:

keys (A (k, N) array or tuple containing k (N,)-shaped sequences) – The k different columns to be sorted. The last column (or row if keys is a 2D array) is the primary sort key.
axis (int) – Axis to be indirectly sorted.
kwargs (dict) – Additional keyword arguments.

Return type:

None

abstract sort_taxa(keys, **kwargs)#

Sort slements of the Matrix along the taxa axis using a sequence of keys. Note this modifies the Matrix in-place.

Parameters:

keys (A (k, N) array or tuple containing k (N,)-shaped sequences) – The k different columns to be sorted. The last column (or row if keys is a 2D array) is the primary sort key.
kwargs (dict) – Additional keyword arguments.

Return type:

None

abstract property square_axes: tuple#: Axis indices for axes that are square.

abstract property square_axes_len: tuple#: Axis lengths for axes that are square.

abstract property square_taxa_axes: tuple#: Axis indices for taxa axes that are square.

abstract property square_taxa_axes_len: tuple#: Axis lengths for axes that are square.

abstract property taxa: object#: Taxa label.

abstract property taxa_axis: int#: Axis along which taxa are stored.

abstract property taxa_grp: object#: Taxa group label.

abstract property taxa_grp_len: object#: Taxa group length.

abstract property taxa_grp_name: object#: Taxa group name.

abstract property taxa_grp_spix: object#: Taxa group stop index.

abstract property taxa_grp_stix: object#: Taxa group start index.

abstract to_csv(filename, **kwargs)[source]#

Write an object to a CSV file.

Parameters:

filename (str) – CSV file name to which to write.
kwargs (dict) – Additional keyword arguments to use for dictating export to a CSV.

Return type:

None

abstract to_hdf5(filename, groupname)[source]#

Write an object 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 object data is stored. If None, object is written to the base HDF5 group.

Return type:

None

abstract to_pandas(**kwargs)[source]#

Export a CoancestryMatrix to a pandas.DataFrame.

Parameters:: kwargs (dict) – Additional keyword arguments to use for dictating export to a pandas.DataFrame.
Returns:: out – An output dataframe.
Return type:: pandas.DataFrame

abstract ungroup(axis, **kwargs)#

Ungroup the GroupableMatrix along an axis by removing grouping metadata.

Parameters:

axis (int) – The axis along which values should be ungrouped.
kwargs (dict) – Additional keyword arguments.

Return type:

None

abstract ungroup_taxa(**kwargs)#

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

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