mdciao.nomenclature.LabelerGPCR¶

class mdciao.nomenclature.LabelerGPCR(uniprot_name, ref_PDB=None, GPCR_scheme='display_generic_number', local_path='.', format='%s.xlsx', verbose=True, try_web_lookup=True, write_to_disk=False)¶

Obtain and manipulate GPCR notation.

This is based on the awesome GPCRdb REST-API, and follows the different schemes provided there. These schemes can be:

structure based schemes, available for all GPCR classes. You can use them by instantiating with “GPCRdb(A)”, “GPCRdb(B)” etc. The relevant references are:

Isberg et al, (2015) Generic GPCR residue numbers - Aligning topology maps while minding the gaps, Trends in Pharmacological Sciences 36, 22–31, https://doi.org/10.1016/j.tips.2014.11.001

Isberg et al, (2016) GPCRdb: An information system for G protein-coupled receptors, Nucleic Acids Research 44, D356–D364, https://doi.org/10.1093/nar/gkv1178

sequence based schemes, with different names depending on the GPCR class

Class-A: Ballesteros et al, (1995) Integrated methods for the construction of three-dimensional models and computational probing of structure-function relations in G protein-coupled receptors, Methods in Neurosciences 25, 366–428, https://doi.org/10.1016/S1043-9471(05)80049-7

Class-B: Wootten et al, (2013) Polar transmembrane interactions drive formation of ligand-specific and signal pathway-biased family B G protein-coupled receptor conformations, Proceedings of the National Academy of Sciences of the United States of America 110, 5211–5216, https://doi.org/10.1073/pnas.1221585110

Class-C: Pin et al, (2003) Evolution, structure, and activation mechanism of family 3/C G-protein-coupled receptors Pharmacology and Therapeutics 98, 325–354 https://doi.org/10.1016/S0163-7258(03)00038-X

Class-F: Wu et al, (2014) Structure of a class C GPCR metabotropic glutamate receptor 1 bound to an allosteric modulator Science 344, 58–64 https://doi.org/10.1126/science.1249489

Note

Not all schemes might work work for all methods of this class. In particular, fragmentation heuristics are derived from 3.50(x50)-type formats. Other class A schemes like Oliveira and Baldwin-Schwarz can be used for residue mapping, labeling, but not for fragmentation. They are still partially usable but we have decided to omit them from the docs. Please see the full reference page for their citation.

__init__(uniprot_name, ref_PDB=None, GPCR_scheme='display_generic_number', local_path='.', format='%s.xlsx', verbose=True, try_web_lookup=True, write_to_disk=False)¶

Parameters

uniprot_name (str) – Descriptor by which to find the nomenclature, it gets directly passed to GPCR_finder Can be anything that can be used to try and find the needed information, locally or online: * a uniprot descriptor, e.g. adrb2_human * a full local filename * a part of a local filename Please note the difference between UniProt Accession Code and UniProt entry name as explained here.
GPCR_scheme (str, default is 'display_generic_number') – The GPCR nomenclature scheme to use. The default is to use what the GPCRdb itself has chosen for this particular uniprot code. Not all schemes will be available for all choices of uniprot_name. You can choose from: ‘BW’, ‘Wootten’, ‘Pin’, ‘Wang’, ‘Fungal’, ‘GPCRdb(A)’, ‘GPCRdb(B)’, ‘GPCRdb(C)’, ‘GPCRdb(F)’, ‘GPCRdb(D)’, ‘Oliveira’, ‘BS’, but not all are guaranteed to work
ref_PDB (str, default is None) – If passed, this structure will be downloaded and attached as an Trajectory object to this to this LabelerGPCR object as its LabelerGPCR.geom attribute
local_path (str, default is ".") – Since the uniprot_name is turned into a filename in case it’s a descriptor, this is the local path where to (potentially) look for files. In case uniprot_name is just a filename, we can turn it into a full path to a local file using this parameter, which is passed to GPCR_finder and LabelerConsensus. Note that this optional parameter is here for compatibility reasons with other methods and might disappear in the future.
format (str, default is "%s.xlsx") – How to construct a filename out of uniprot_name
verbose (bool, default is True) – Be verbose. Gets passed to GPCR_finder LabelerConsensus
try_web_lookup (bool, default is True) – Try a web lookup on the GPCRdb of the uniprot_name. If uniprot_name is e.g. “adrb2_human.xlsx”, including the extension “xslx”, then the lookup will fail. This what the format parameter is for
write_to_disk (bool, default is False) – Save an excel file with the nomenclature information

Methods

`__init__`(uniprot_name[, ref_PDB, …])	param uniprot_name Descriptor by which to find the nomenclature,
`aligntop`(top[, restrict_to_residxs, …])	Align a topology with the object’s sequence.
`conlab2residx`(top[, map])	Returns a dictionary keyed by consensus labels and valued by residue indices of the input topology in `top`.
`top2frags`(top[, fragments, min_hit_rate, …])	Return the subdomains derived from the consensus nomenclature and map it out in terms of residue indices of the input `top`
`top2labels`(top[, allow_nonmatch, …])	Align the sequence of `top` to the sequence used to initialize this `LabelerConsensus` and return a list of consensus labels for each residue in `top`.

Attributes

`AA2conlab`	Dictionary with short AA-codes as keys, so that e.g.
`conlab2AA`	Dictionary with consensus labels as keys, so that e.g.
`conlab2idx`	Dictionary with consensus labels as keys and zero-indexed row-indices of self.dataframe, as values so that e.g.
`dataframe`	`DataFrame` summarizing this object’s information
`fragment_names`	Name of the fragments according to the consensus labels
`fragments`	Dictionary of fragments keyed with fragment names and valued with the residue names (AAresSeq) in that fragment.
`fragments_as_conlabs`	Dictionary of fragments keyed with fragment names and valued with the consensus labels in that fragment
`fragments_as_idxs`	Dictionary of fragments keyed with fragment names and valued with idxs of the first column of self.dataframe, regardless of these residues having a consensus label or not
`geom`	`Trajectory` with with what was found (locally or online) using `ref_PDB`
`idx2conlab`	List of consensus labels in the order (=idx) they appear in the original dataframe
`most_recent_alignment`	A `DataFrame` with the most recent alignment
`most_recent_top2labels`	The most recent `self.top2labels`-result
`ref_PDB`	PDB code used for instantiation
`seq`	The reference sequence in `dataframe`
`tablefile`	The file used to instantiate this transformer
`top`	`Topology` with with what was found (locally or online) using `ref_PDB`
`uniprot_name`

property AA2conlab¶: Dictionary with short AA-codes as keys, so that e.g. * self.AA2conlab[“R131”] -> ‘3.50’ * self.AA2conlab[“R201”] -> “G.hfs2.2”

aligntop(top, restrict_to_residxs=None, min_hit_rate=0.5, fragments='resSeq', verbose=False)¶

Align a topology with the object’s sequence. Returns two maps (top2self, self2top) and populates the attribute self.most_recent_alignment

Wraps around mdciao.utils.sequence.align_tops_or_seqs

The indices of self are indices (row-indices) of the original dataframe, which are the ones in seq

Parameters

top (Topology object or string) –
restrict_to_residxs (iterable of integers, default is None) – Use only these residues for alignment and labelling purposes. Helps “guide” the alignment method. E.g., for big topologies the the alignment might find some small matches somewhere and, in some corner cases, match those instead of the desired ones. Here, one can pass residues indices defining the topology segment wherein the match should be contained to.
min_hit_rate (float, default .5) – With big topologies and many fragments, the alignment method (mdciao.sequence.my_bioalign) sometimes yields sub-optimal results. A value min_hit_rate >0, e.g. .5 means that a pre-alignment takes place to populate restrict_to_residxs with indices of those the fragments (mdciao.fragments.get_fragments defaults) with more than 50% alignment in the pre-alignment. If min_hit_rate>0, :obj`restrict_to_residx` has to be None.
fragments (str, iterable, None, or bool, default is 'resSeq') –
Fragment definitions to resolve situations where two (or more) alignments share the optimal alignment score. Consider aligning an input sequence ‘XXLXX’ to the object’s sequence ‘XXLLXX’. There are two equally scored alignments:
```
XXL XX      XX LXX
||| ||  vs  || |||
XXLLXX      XXLLXX
```
In order to choose between these two alignments, it’s checked which alignment observes the fragment definition passed here. This definition can be passed explicitly as iterable of integers or implicitly as a fragmentation heuristic, which will be used by mdciao.fragments.get_fragments on the top. So, if e.g. the input ‘XXLXX’ sequence is fragmented (explicitly or implicitly) into [XX],[LXX], then the second alignment will be chosen, given that it respects that fragmentation.
Note
fragments only has an effect if both
- the top is an actual Topology carrying the sequence
indices, since if top is a sequence string, then there’s no fragmentation heuristic possible.
- two or more alignments share the optimal alignment score
The method avoids breaking the consensus definitions across the input fragments, while also providing consensus definitions for those other residues not present in fragments. This is done by using ‘resSeq’ to infer the missing fragmentation. This keeps the functionality of respecting the original fragments while also providing consensus fragmentation other parts of the topology. For compatibility with other methods, passing fragments=None will still use the fragmentation heuristic (this might change in the future). To explicitly circumvent this forced fragmentation and subsequent check, use `fragments=False`. This will simply use the first alignment that comes out of :obj:`mdciao.utils.sequence.my_bioalign`, regardless of there being other, equally scored, alignments and potential clashes with sensitive fragmentations.
verbose (boolean, default is False) – be verbose

Returns

top2self (dict) – Maps indices of top to indices of this objects self.seq
self2top (dict) – Maps indices of this object’s seq.seq to indices of this self.seq

property conlab2AA¶: Dictionary with consensus labels as keys, so that e.g. * self.conlab2AA[“3.50”] -> ‘R131’ or * self.conlab2AA[“G.hfs2.2”] -> ‘R201’

property conlab2idx¶: Dictionary with consensus labels as keys and zero-indexed row-indices of self.dataframe, as values so that e.g. * self.conlab2AA[“3.50”] -> ‘R131’ or * self.conlab2AA[“G.hfs2.2”] -> ‘R201’

conlab2residx(top, map=None, **top2labels_kwargs)¶

Returns a dictionary keyed by consensus labels and valued by residue indices of the input topology in top.

The default behaviour is to internally align top with the object’s available consensus dictionary on the fly using self.top2labels. See the docs there for **top2labels_kwargs, in particular restrict_to_residxs, keep_consensus, and min_hit_rate

Note

This method is able to work with a new topology every time, performing a sequence alignment every call. The intention is to instantiate a LabelerConsensus just one time and use it with as many topologies as you like without changing any attribute of self.

HOWEVER, if you know what you are doing, you can provide a list of consensus labels yourself using map. Then, this method is nothing but a table lookup (almost)

Warning

No checks are performed to see if the input of map actually matches the residues of top in any way, so that the output can be rubbish and go unnoticed.

Parameters

top (Topology) –
map (list, default is None) – A pre-computed residx2consensuslabel map, i.e. the output of a previous, external call to _top2consensus_map If it contains duplicates, it is a malformed list. See the note above for more info

Returns

dict

Return type

keyed by consensus labels and valued with residue idxs

property dataframe¶

DataFrame summarizing this object’s information

Returns: df
Return type: DataFrame

property fragment_names¶

Name of the fragments according to the consensus labels

TODO OR NOT? Check!

property fragments¶: Dictionary of fragments keyed with fragment names and valued with the residue names (AAresSeq) in that fragment.

property fragments_as_conlabs¶: Dictionary of fragments keyed with fragment names and valued with the consensus labels in that fragment

property fragments_as_idxs¶: Dictionary of fragments keyed with fragment names and valued with idxs of the first column of self.dataframe, regardless of these residues having a consensus label or not

property geom¶: Trajectory with with what was found (locally or online) using ref_PDB

property idx2conlab¶

List of consensus labels in the order (=idx) they appear in the original dataframe

This index is the row-index of the table, don’t count on it being aligned with anything

property most_recent_alignment¶

A DataFrame with the most recent alignment

Expert use only

Returns: df
Return type: DataFrame

property most_recent_top2labels¶

The most recent self.top2labels-result

Expert use only

Returns: df
Return type: list

property ref_PDB¶: PDB code used for instantiation

property seq¶: The reference sequence in dataframe

property tablefile¶: The file used to instantiate this transformer

property top¶: Topology with with what was found (locally or online) using ref_PDB

top2frags(top, fragments=None, min_hit_rate=0.5, input_dataframe=None, show_alignment=False, verbose=True)¶

Return the subdomains derived from the consensus nomenclature and map it out in terms of residue indices of the input top

Note

This method uses aligntop internally, see the doc on that method for more info.

Parameters

top – Topology or path to topology file (e.g. a pdb)
fragments (iterable of integers, default is None) –
The user can parse an existing list of fragment-definitions (via residue idxs) to check if the newly found, consensus definitions (defs) clash with the input in fragments. Clash means that the defs would span over more than one of the fragments in defined in fragments.

An interactive prompt will ask the user which fragments to keep in case of clashes.

Check check_if_subfragment for more info
min_hit_rate (float, default is .5) – With big topologies, like a receptor-Gprotein system, the “brute-force” alignment method (check mdciao.sequence.my_bioalign) sometimes yields sub-optimal results, e.g. finding short snippets of reference sequence that align in a completely wrong part of the topology. To avoid this, an initial, exploratory alignment is carried out. min_hit_rate = .5 means that only the fragments (mdciao.fragments.get_fragments defaults) with more than 50% alignment in this exploration are used to improve the second alignment
input_dataframe (DataFrame, default is None) – Expert option, use at your own risk. Instead of aligning top to the object’s sequence to derive fragment definitions, input an existing alignment here, e.g. the self.most_recent_alignment
show_alignment (bool, default is False,) – Show the entire alignment as DataFrame
verbose (bool, default is True) – Also print the definitions

Returns

defs – Dictionary with subdomain names as keys and lists of indices as values

Return type

dictionary

top2labels(top, allow_nonmatch=True, autofill_consensus=True, min_hit_rate=0.5, **aligntop_kwargs)¶

Align the sequence of top to the sequence used to initialize this LabelerConsensus and return a list of consensus labels for each residue in top.

Populates the attributes most_recent_top2labels and most_recent_alignment

If a consensus label is returned as None it means one of two things:

this position was successfully aligned with a match but the data used to initialize this ConsensusLabeler did not contain a label

this position has a label in the original data but the sequence alignment is not matched (e.g., bc of a point mutation)

To remedy the second case a-posteriori two things can be done:

recover the original label even though residues did not match, using allow_nonmatch. See alignment_df2_conslist for more info

reconstruct what the label could be using a heuristic to “autofill” the consensus labels, using autofill_consensus. See _fill_consensus_gaps for more info

Note

This method uses aligntop internally, see the doc on that method for more info.

Parameters

top – Topology object
allow_nonmatch (bool, default is True) – Use consensus labels for non-matching positions in case the non-matches have equal lengths
autofill_consensus (boolean default is False) –
Even if there is a consensus mismatch with the sequence of the input AA2conlab_dict, try to relabel automagically, s.t.
- [‘G.H5.25’, ‘G.H5.26’, None, ‘G.H.28’]
will be grouped relabeled as * [‘G.H5.25’, ‘G.H5.26’, ‘G.H.27’, ‘G.H.28’]
min_hit_rate (float, default is .5) – With big topologies and many fragments, the alignment method (mdciao.sequence.my_bioalign) sometimes yields sub-optimal results. A value min_hit_rate >0, e.g. .5 means that a pre-alignment takes place to populate restrict_to_residxs with indices of those the fragments (mdciao.fragments.get_fragments defaults) with more than 50% alignment in the pre-alignment.

Returns

map

Return type

list of len = top.n_residues with the consensus labels