Internal Base Class

class aaindex._aaindex_matrix.Map(*args, **kwargs)

A dict subclass that enables attribute-style (dot notation) access to keys.

Works for nested dicts. Each AAindex record returned by __getitem__ is wrapped in this class so fields can be read as record.description as well as record[‘description’].

References

https://stackoverflow.com/questions/2352181/how-to-use-a-dot-to-access-members-of-dictionary

class aaindex._aaindex_matrix._AAIndexMatrix(filename: str)

Base class for AAindex2 and AAindex3 matrix database parsers.

Provides shared parsing, lookup, search, and protocol methods for the lower-triangular 20x20 matrix databases. Subclasses call super().__init__(filename) with the appropriate base filename so the correct data file is loaded.

aaindex_module_path

Absolute path to the aaindex package directory.

data_dir

Subdirectory name containing raw and cached data files.

aaindex_filename

Base filename for this database (no extension).

aaindex_json

Parsed database keyed by accession number.

last_updated

Date string of the last published database update.

__contains__(record_code: object) → bool

Return True if record_code exists in the database.

__getitem__(record_code: str) → Map

Return a record by accession number wrapped in a Map (dot-notation dict).

Parameters:

record_code – AAindex accession number (case-insensitive, leading/trailing whitespace is stripped).

Returns:

Record data as a Map, accessible via dict or dot notation.

Raises:

• TypeError – If record_code is not a string.

• ValueError – If record_code is not found in the database.

__iter__() → Iterator[str]

Iterate over all accession numbers in the database.

__len__() → int

Return total number of records in the database.

__repr__() → str

Return a canonical string representation of this instance.

__sizeof__() → int

Return the on-disk size of the raw AAindex data file in bytes.

property aaindex_filename: str

property aaindex_json: dict

Parsed database dict, loaded lazily on first access.

amino_acids() → list[str]

Return sorted list of the 20 canonical amino acid single-letter codes.

Derived from the row_order field of the first record in the database. Result is cached after the first call.

Returns:

Sorted list of single-letter amino acid codes.

property data_dir: str

get(record_code: str, aa1: str, aa2: str) → float | None

Return the pairwise matrix score for two amino acids from a given record.

For symmetric (lower-triangular) records, get(code, aa1, aa2) == get(code, aa2, aa1). For non-symmetric records, order matters: get(code, aa1, aa2) may differ from get(code, aa2, aa1). Returns None when the amino acid pair has an NA value in the source data or when the amino acid letter is not present in this record’s matrix.

Parameters:

• record_code – AAindex accession number.

• aa1 – Single-letter code for the first amino acid (row).

• aa2 – Single-letter code for the second amino acid (column).

Returns:

Pairwise score as float, or None if data is not available.

Raises:

• TypeError – If aa1 or aa2 are not strings.

• ValueError – If record_code is not found in the database.

property last_updated: str

num_records() → int

Return the total number of records in the database.

Returns:

Number of records as int.

parse_aaindex() → dict

Deprecated: use _parse_aaindex() instead.

Deprecated since version This: method is an internal implementation detail and will be removed in a future version.

plot_heatmap(record_code: str) → Any

Plot the pairwise amino acid matrix for a record as a heatmap.

Requires matplotlib to be installed. NA values (None) in the matrix are rendered as white / masked cells.

Parameters:

record_code – AAindex accession number.

Returns:

matplotlib.axes.Axes containing the heatmap. The figure can be displayed with plt.show() or saved with plt.savefig().

Raises:

• ImportError – If matplotlib is not installed.

• ValueError – If record_code is not found in the database.

Example

>>> ax = aaindex2.plot_heatmap('ALTS910101')
>>> import matplotlib.pyplot as plt; plt.show()

record_codes() → list[str]

Return sorted list of all accession numbers in the database.

Returns:

Sorted list of accession number strings.

record_names() → list[str]

Return a list of description strings for all records.

Returns:

List of description strings in database insertion order.

search(query: str | list[str]) → dict

Search records by keyword(s) across all text fields.

Searches description, accession code, PMID, references, and notes. Matching is case-insensitive. Results are returned sorted by accession number.

Parameters:

query – Keyword string or list of keyword strings.

Returns:

Dict of matching records keyed by accession number, sorted alphabetically. Returns an empty dict if no records match.

Raises:

TypeError – If query is not a str or list.

search_fuzzy(query: str, n: int = 10, cutoff: float = 0.0) → dict

Search records using fuzzy matching with ranked results.

Scores each record by how closely query matches any of its text fields (description, accession code, PMID, references, notes) using difflib.SequenceMatcher. Results are returned in descending score order (most relevant first) with no external dependencies.

Parameters:

• query – Search string.

• n – Maximum number of results to return. Defaults to 10.

• cutoff – Minimum similarity score in [0, 1] to include a record. Defaults to 0.0 (all records scored, top n returned).

Returns:

Dict of matching records keyed by accession number, ordered by descending similarity score.

Raises:

• TypeError – If query is not a str.

• ValueError – If n < 1 or cutoff is outside [0, 1].

to_dataframe(record_code: str | None = None) → Any

Export pairwise matrix scores as a pandas DataFrame.

Requires pandas to be installed. If pandas is not available a clear ImportError is raised rather than a silent failure.

When record_code is given the returned DataFrame is the full 20×20 (or N×N) matrix for that record, with row and column labels from row_order and col_order. When record_code is None a MultiIndex DataFrame is returned with index levels (accession, row_aa) and column labels from col_order.

Parameters:

record_code – If given, export only that record’s matrix. If None (default), export all records.

Returns:

pandas.DataFrame representing the requested matrix data.

Raises:

• ImportError – If pandas is not installed.

• ValueError – If record_code is not found in the database.

to_dict(record_code: str | None = None) → dict

Export one record or the full database as a plain Python dict.

Parameters:

record_code – If given, export only that record keyed by its accession number. If None (default), export the entire database.

Returns:

Dict containing the requested records.

Raises:

ValueError – If record_code is not found in the database.

to_json(record_code: str | None = None, indent: int = 4) → str

Serialise one record or the full database to a JSON string.

Parameters:

• record_code – If given, serialise only that record. If None (default), serialise the entire database.

• indent – JSON indentation level. Defaults to 4.

Returns:

JSON-formatted string.

Raises:

ValueError – If record_code is not found in the database.

values(record_code: str) → dict

Return the full 20x20 matrix dict for a given record.

Shortcut to avoid accessing the whole record when only the matrix is needed. Consistent with AAIndex1.values() which returns amino acid values.

Parameters:

record_code – AAindex accession number.

Returns:

Nested dict of pairwise scores keyed by single-letter amino acid codes.

Raises:

ValueError – If record_code is not found in the database.