AAindex3

The AAindex3 section contains 47 statistical protein contact potentials and follows the same record format as AAindex2. Each entry stores a 20 × 20 matrix of pairwise contact potential scores derived from statistical analysis of protein structures.

Record format

************************************************************************
*                                                                      *
* Each entry has the following format.                                 *
*                                                                      *
* H Accession number                                                   *
* D Data description                                                   *
* R PMID                                                               *
* A Author(s)                                                          *
* T Title of the article                                               *
* J Journal reference                                                  *
* * Comment or missing                                                 *
* M rows = ARNDCQEGHILKMFPSTWYV, cols = ARNDCQEGHILKMFPSTWYV           *
*   AA                                                                 *
*   AR RR                                                              *
*   AN RN NN                                                           *
*   AD RD ND DD                                                        *
*   AC RC NC DC CC                                                     *
*   AQ RQ NQ DQ CQ QQ                                                  *
*   AE RE NE DE CE QE EE                                               *
*   AG RG NG DG CG QG EG GG                                            *
*   AH RH NH DH CH QH EH GH HH                                         *
*   AI RI NI DI CI QI EI GI HI II                                      *
*   AL RL NL DL CL QL EL GL HL IL LL                                   *
*   AK RK NK DK CK QK EK GK HK IK LK KK                                *
*   AM RM NM DM CM QM EM GM HM IM LM KM MM                             *
*   AF RF NF DF CF QF EF GF HF IF LF KF MF FF                          *
*   AP RP NP DP CP QP EP GP HP IP LP KP MP FP PP                       *
*   AS RS NS DS CS QS ES GS HS IS LS KS MS FS PS SS                    *
*   AT RT NT DT CT QT ET GT HT IT LT KT MT FT PT ST TT                 *
*   AW RW NW DW CW QW EW GW HW IW LW KW MW FW PW SW TW WW              *
*   AY RY NY DY CY QY EY GY HY IY LY KY MY FY PY SY TY WY YY           *
*   AV RV NV DV CV QV EV GV HV IV LV KV MV FV PV SV TV WV YV VV        *
* //                                                                   *
************************************************************************
class aaindex.aaindex3.AAIndex3[source]

Bases: _AAIndexMatrix

Python parser for AAindex3: Amino Acid Contact Potential Matrix Database.

Inherits all parsing, search, and lookup functionality from _AAIndexMatrix. Stores the 47 known 20x20 contact potential matrices from AAindex3 (http://www.genome.jp/aaindex/).

References

[1]: Kawashima, S. and Kanehisa, M.; AAindex: amino acid index database.

Nucleic Acids Res. 28, 374 (2000).

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

References

[1] Kawashima, S. and Kanehisa, M.; AAindex: amino acid index database. Nucleic Acids Res. 28, 374 (2000).