API reference

The package root

from domainator import parse_seqfiles, write_genbank, DataMatrix, DomainatorError

domainator.seqio.parse_seqfiles(seqfiles, contigs=None, filetype_override=None, seek_to=None, max_recs=float('inf'), default_molecule_type='protein', genbank_parser=None)

Read the records of GenBank and FASTA files, one at a time.

Parameters:

Name	Type	Description	Default
seqfiles	Iterable[Union[str, PathLike, IO]]	GenBank or FASTA paths or open handles. "-" or "/dev/stdin" reads standard input, as GenBank unless filetype_override says otherwise.	required
contigs	Optional[Container[str]]	yield only the records with these ids (any container, such as a set or the keys of a dict). None yields every record.	None
filetype_override	Optional[str]	"genbank" or "fasta", instead of guessing the format from the file extension. Required for handles.	None
seek_to	Optional[int]	seek to this byte offset in the file before reading any records.	None
max_recs	float	stop reading each file after yielding this many of its records.	float('inf')
default_molecule_type	str	the molecule_type of records that don't declare one, such as FASTA records.	'protein'
genbank_parser	Optional[str]	which GenBank backend to use, "lean" or "biopython" (the default). "lean" uses the optional native (Rust) parser and yields LeanContig objects; it is much faster, but falls back to Biopython for records it cannot parse and when the native extension is not built.	None

Yields:

Type	Description
SeqRecord	The records, as SeqRecords (or LeanContigs with genbank_parser="lean").

domainator.seqio.write_genbank(seq_records, file_name, default_molecule_type='DNA')

Write SeqRecords as GenBank, to a file name or a handle. The records are not changed.

Each record is written as parse_seqfiles would read it back: its id goes in the LOCUS line (with spaces removed) and its name in ACCESSION. Records without a molecule type get default_molecule_type, and records without a date get today's. Features are written in order of start position, and each CDS gets a domainator_ qualifier summarizing the Domainator domains on it (and loses any for databases with no domains left).

domainator.data_matrix.DataMatrix(data, row_names, col_names, row_lengths=None, col_lengths=None, data_type=None, *, copy_data=True)

A labeled 2D matrix stored as a canonical scipy.sparse.csr_array.

Attributes:

Name	Type	Description
data	csr_array	scipy.sparse.csr_array holding the values. Assigning to it re-canonicalizes the new value. Changing data.data in place is allowed, but then call eliminate_zeros() on it if any value became 0.
rows		List of row labels
columns		List of column labels
row_to_idx		Dictionary mapping row names to indices
column_to_idx		Dictionary mapping column names to indices (same object as row_to_idx if symmetric)
row_lengths		Sequence lengths for rows as numpy array, or None
column_lengths		Sequence lengths for columns as numpy array, or None
data_type		String describing the kind of values, empty string if not specified

Parameters:

Name	Type	Description	Default
data	Union[ndarray, sparray, spmatrix]	2D numpy array, scipy sparse array/matrix, or array-like. Converted to a canonical CSR array.	required
row_names	List[str]	List of row labels, length must match data.shape[0]	required
col_names	List[str]	List of column labels, length must match data.shape[1]	required
row_lengths	Optional[ndarray]	Optional sequence lengths for rows (array-like, stored as numpy array)	None
col_lengths	Optional[ndarray]	Optional sequence lengths for columns (array-like, stored as numpy array)	None
data_type	Optional[str]	Optional string describing the data type (e.g., 'score', 'norm_score', 'score_dist')	None
copy_data	bool	If False and data is already a CSR array, reuse it (canonicalizing it in place) instead of copying it.	True

Raises:

Type	Description
ValueError	If data dimensions don't match label lengths

exactly_symmetric property

True if labels are symmetric and every value equals its transpose exactly.

This is the condition for upper-triangle storage. The result is cached until data is reassigned.

nnz property

Return number of stored (non-zero) values.

shape property

Return shape of the matrix as (rows, columns).

size property

Returns:

Name	Type	Description
int	int	number of cells in the matrix

symmetric property

Returns True if both labels and values are symmetric.

symmetric_labels property

Returns True if row and column labels are identical.

symmetric_values property

Returns True if the matrix has symmetric values. Uses np.allclose to allow for floating point imprecision.

__len__()

Return number of rows in the matrix.

__repr__()

Return detailed string representation for debugging.

__str__()

Return readable string representation.

estimate_hdf_size(matrix, row_names, col_names, row_lengths=None, col_lengths=None, data_type='', symmetric=None) classmethod

Estimate the size of write_hdf output in bytes (symmetric as in write_hdf).

estimate_write_size(output_type, matrix, row_names, col_names, row_lengths=None, col_lengths=None, data_type='', symmetric=None) classmethod

Estimate the size of a matrix output in bytes; symmetric only affects "hdf".

from_file(matrix_file, lower_bound=None) classmethod

Load a matrix from a Domainator hdf5 file or a tab-separated dense text file.

Parameters:

Name	Type	Description	Default
matrix_file	Union[PathLike, str]	path to the file. hdf5 is recognized by its extension (.hdf5, .hdf, .h5); anything else is read as dense text.	required
lower_bound	Optional[float]	if set, values <= lower_bound are dropped (set to 0) after loading. NaNs are kept.	None

iter_data(index_style='name', skip_zeros=True)

Iterate over matrix values in row-major order, yielding (row_identifier, col_identifier, value).

Parameters:

Name	Type	Description	Default
index_style	str	Either "name" (return row/column names) or "index" (return integer indices)	'name'
skip_zeros	bool	If True, only yield stored (non-zero) values	True

itervalues()

Yield all values row by row, zeros included.

names_dict_to_list(names_dict) staticmethod

Converts a dict of indexes into a list of keys

Parameters:

Name	Type	Description	Default
names_dict	Dict[str, int]	{row_name: row_index}	required

Returns:

Type	Description
List[str]	List[str]: List of strings where list[row_index] = row_name

require_similarity(tool)

Raise if this matrix holds distances, for tools where 0 must mean "no edge".

sorted_undirected_edges(skip_zeros=False, agg=None)

Return lower-triangular undirected edges sorted by descending score.

agg=None or the builtin max take a vectorized path; any other callable is applied element-wise via triangular.

toarray()

Return matrix as a dense numpy array (zeros included).

triangular(include_diagonal=False, skip_zeros=False, index_style='name', agg=None)

Return the lower triangle of the matrix as a list of tuples (see triangular_iter).

triangular_iter(include_diagonal=False, skip_zeros=False, index_style='name', agg=None)

Iterate over the lower triangle of a square matrix, in row-major order.

Parameters:

Name	Type	Description	Default
include_diagonal	bool	If True, include diagonal elements	False
skip_zeros	bool	If True, exclude zero values from results	False
index_style	str	Either "name" (return row/column names) or "index" (return integer indices)	'name'
agg	Optional[Callable[[float, float], float]]	Optional function combining each value with its transpose, e.g. max, yielding agg(M[r, c], M[c, r]). With skip_zeros, a position is skipped when both cells are 0; for the builtin max it is also skipped when the result is 0 (which only happens with negative values).	None

Yields:

Type	Description
Tuple[Union[str, int], Union[str, int], float]	(row_identifier, col_identifier, value) tuples.

Raises:

Type	Description
NotImplementedError	If matrix is not square

validate_matrix_data(matrix, row_names, col_names, row_lens=None, col_lens=None) classmethod

Check for consistency between a matrix and row/column labels

Parameters:

Name	Type	Description	Default
matrix	Union[array, sparray]	dense or sparse data matrix	required
row_names	List[str]	List[str]: row labels	required
col_names	List[str]	List[str]: column labels	required

Returns:

Type	Description
Tuple[List[str], List[str]]	(row_names, col_names) as lists; col_names is the same object as row_names if they are equal.

write(file_name, output_type='hdf')

Write the matrix to a file.

Parameters:

Name	Type	Description	Default
file_name	Union[PathLike, str]	Path to the output file	required
output_type	str	"hdf" (Domainator hdf5) or "dense_text" (TSV)	'hdf'

Raises:

Type	Description
ValueError	If output_type is not recognized

write_dense_text(matrix, file_name, row_names, col_names, row_lengths=None, col_lengths=None, data_type='') classmethod

Writes a matrix to a tab-separated text file, every cell included.

Parameters:

Name	Type	Description	Default
matrix	Union[array, sparray]	2d array	required
file_name	Union[PathLike, str]	path to the target file to write the data to. "-" or "/dev/stdout" writes standard output.	required
row_names	List[str]	List[str]: row labels	required
col_names	List[str]	List[str]: column labels	required

write_hdf(matrix, file_name, row_names, col_names, row_lengths=None, col_lengths=None, data_type='', symmetric=None) classmethod

Writes a matrix to a Domainator hdf5 file in CSR format.

Zeros are dropped and indices sorted. When the row and column labels (and lengths) are the same and the values are exactly symmetric, only the upper triangle (including the diagonal) is stored.

Parameters:

Name	Type	Description	Default
matrix	Union[ndarray, sparray, spmatrix]	numpy array or scipy sparse array/matrix. Not modified.	required
symmetric	Optional[bool]	None (default) detects exact symmetry. True asserts the values are exactly symmetric (skips the check; a wrong assertion loses the lower triangle). False always stores the full matrix.	None

domainator.errors

Exceptions Domainator raises for problems a user can fix.

The domainator command prints a DomainatorError as a one-line message, without a traceback (-v shows the traceback). Each subclass also derives from the built-in exception it refines, so except ValueError and except RuntimeError keep catching them.

DomainatorError

Bases: Exception

Base class for errors caused by inputs, options, or the environment, not by a bug.

ExternalToolError

Bases: DomainatorError, RuntimeError

An external program (diamond, cd-hit, foldseek, ...) is missing or failed.

FormatVersionError

Bases: DomainatorError, ValueError

A file was written in a format version this Domainator can't read.

InputError

Bases: DomainatorError, ValueError

An input file or option value can't be used.

OutputSizeLimitExceeded

Bases: DomainatorError, RuntimeError

An output would exceed the --max_output_gb guardrail.

Feature types

DOMAIN_FEATURE_NAME ("Domainator") and DOMAIN_SEARCH_BEST_HIT_NAME ("Domain_Search") are the GenBank feature types of domain annotations and domain_search hits; see the qualifier reference.