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 workref_PDB (str, default is None) – If passed, this structure will be downloaded and attached as an
Trajectory
object to this to thisLabelerGPCR
object as itsLabelerGPCR.geom
attributelocal_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 caseuniprot_name
is just a filename, we can turn it into a full path to a local file using this parameter, which is passed toGPCR_finder
andLabelerConsensus
. 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
. Ifuniprot_name
is e.g. “adrb2_human.xlsx”, including the extension “xslx”, then the lookup will fail. This what theformat
parameter is forwrite_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 thisLabelerConsensus
and return a list of consensus labels for each residue intop
.Attributes
Dictionary with short AA-codes as keys, so that e.g.
Dictionary with consensus labels as keys, so that e.g.
Dictionary with consensus labels as keys and zero-indexed row-indices of self.dataframe, as values so that e.g.
DataFrame
summarizing this object’s informationName of the fragments according to the consensus labels
Dictionary of fragments keyed with fragment names and valued with the residue names (AAresSeq) in that fragment.
Dictionary of fragments keyed with fragment names and valued with the consensus labels in that fragment
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
Trajectory
with with what was found (locally or online) usingref_PDB
List of consensus labels in the order (=idx) they appear in the original dataframe
A
DataFrame
with the most recent alignmentThe most recent
self.top2labels
-resultPDB code used for instantiation
The reference sequence in
dataframe
The file used to instantiate this transformer
Topology
with with what was found (locally or online) usingref_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 inseq
- 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 valuemin_hit_rate
>0, e.g. .5 means that a pre-alignment takes place to populaterestrict_to_residxs
with indices of those the fragments (mdciao.fragments.get_fragments
defaults) with more than 50% alignment in the pre-alignment. Ifmin_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 usingself.top2labels
. See the docs there for **top2labels_kwargs, in particular restrict_to_residxs, keep_consensus, and min_hit_rateNote
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 ofself
.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 oftop
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
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) usingref_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 alignmentExpert use only
- Returns
df
- Return type
-
property
most_recent_top2labels
¶ The most recent
self.top2labels
-resultExpert use only
- Returns
df
- Return type
list
-
property
ref_PDB
¶ PDB code used for instantiation
-
property
tablefile
¶ The file used to instantiate this transformer
-
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 infomin_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 alignmentinput_dataframe (
DataFrame
, default is None) – Expert option, use at your own risk. Instead of aligningtop
to the object’s sequence to derive fragment definitions, input an existing alignment here, e.g. the self.most_recent_alignmentshow_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 thisLabelerConsensus
and return a list of consensus labels for each residue intop
.Populates the attributes
most_recent_top2labels
andmost_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 labelthis 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
. Seealignment_df2_conslist
for more inforeconstruct 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
objectallow_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 valuemin_hit_rate
>0, e.g. .5 means that a pre-alignment takes place to populaterestrict_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