##
## API into metapredict
##
## For all APIS we do do not make hard dependencies, safe informative
## import checking should be done.
##
import inspect
from shephard.exceptions import APIException
## Check metapredict is installed. Note we deliberately do NOT run a prediction
## here - importing this module should be free, so the version check happens
## lazily the first time one of the API functions is actually called.
try:
import metapredict as meta
except ModuleNotFoundError:
meta = None
## ------------------------------------------------------------------------
##
def _check_metapredict():
"""
Internal function that ensures metapredict is installed and is a version
we can work with. Called at the top of every public function in this
module.
Returns
-----------------
None
No return type, but raises an APIException if metapredict is missing
or too old.
"""
if meta is None:
raise APIException('Unable to import metapredict.\nTo use the metapredict API, make sure metapredict is installed. This can be done as follows:\n\npip install metapredict')
# metapredict V3 introduced the version keyword, so its absence tells us we
# are working with an older release
if 'version' not in inspect.signature(meta.predict_disorder).parameters:
raise APIException('SHEPHARD requires metapredict V3 or higher. Please upgrade:\n\npip install --upgrade metapredict')
## ------------------------------------------------------------------------
##
[docs]
def annotate_proteome_with_disorder_track(proteome,
name='disorder',
device=None,
version=3,
show_progress_bar=True,
safe=True):
"""
Function that annotates a proteome with disorder Tracks
for every protein.
By default, disorder Tracks are named 'disorder', although
this can be changed by setting the `name` parameter.
Disorder prediction uses the batch mode in metapredict, which
leverages parallel predictions automatically on GPUs or CPUs.
However, if a specific device is requested, this can be passed
Parameters
-----------------
proteome : shephard.proteome.Proteome
Proteome object to be annotated.
name : str
Name of the Track added to each Protein.
Default = 'disorder'
device : int or str
Identifier for the device to be used for predictions.
Possible inputs: 'cpu', 'mps', 'cuda', or an int that corresponds to
the index of a specific cuda-enabled GPU. If 'cuda' is specified and
cuda.is_available() returns False, instead of falling back to CPU,
metapredict will raise an Exception so you know that you are not
using CUDA as you were expecting.
The default is None, which means we check if there is a
cuda-enabled GPU and, if there is, try to use it. If an int is
passed we use cuda:<int> as the device, where the GPU numbering is
0-indexed (so 0 corresponds to the first GPU). Only set this if you
know which GPU you want to use. Note that MPS is only supported in
PyTorch 2.1 or later, and is still fairly new, so use it at your own
risk.
version : int
Defines the metapredict version to use (must be one of 1, 2
or 3).
show_progress_bar : bool
Flag which, if set to True, means a progress bar is printed as
predictions are made, while if False no progress bar is printed.
Default = True
safe : bool
Flag which, if set to False, means the function overwrites
existing tracks and domains if present. If True, overwriting
will trigger an exception.
Default = True.
Returns
-----------------
None
No return type, but the Protein objects in the Proteome
will be annotated with per-residue disorder Tracks.
"""
_check_metapredict()
uid2seq = {}
for p in proteome:
uid2seq[p.unique_ID] = p.sequence
# batch predict disorder
D = meta.predict_disorder(uid2seq, device=device, show_progress_bar=show_progress_bar, version=version)
for k in uid2seq:
proteome.protein(k).add_track(name, values=D[k][1], safe=safe)
## ------------------------------------------------------------------------
##
[docs]
def annotate_proteome_with_disordered_domains(proteome,
name='IDR',
disorder_threshold=None,
annotate_folded_domains=False,
folded_domain_name = 'FD',
device=None,
version=3,
show_progress_bar=True,
safe=True):
"""
Function that annotates a proteome with disordered
Domains (IDRs) for every protein.
By default, disordered Domains are named as 'IDR's, although
this can be changed by setting the `name` parameter.
In addition, if requested, folded domains can also be annotated
as those domains which are not IDRs. These folded domains are
named 'FD's by default, although this can be changed by setting
the `folded_domain_name` parameter.
Disorder prediction uses the batch mode in metapredict, which
leverages parallel predictions automatically on GPUs or CPUs.
However, if a specific device is requested this can be passed
Parameters
-----------------
proteome : shephard.proteome.Proteome
Proteome object to be annotated.
name : str
Name to give IDR domains.
disorder_threshold : float
Threshold to be used to define IDRs by the metapredict
domain decomposition algorithm. If set to None (default)
metapredict uses the threshold appropriate for the version
being used, which is what we strongly recommend.
annotate_folded_domains : bool
Flag which, if included, means we ALSO annotate
the regions that are not IDRs as 'FD' (folded
domains), where the name can be changed using
the folded_domain_name variable.
Default = False
folded_domain_name : str
String used to name Folded Domains. Only relevant
if annotate_folded_domains is set to True.
Default = 'FD'
device : int or str
Identifier for the device to be used for predictions.
Possible inputs: 'cpu', 'mps', 'cuda', or an int that corresponds to
the index of a specific cuda-enabled GPU. If 'cuda' is specified and
cuda.is_available() returns False, instead of falling back to CPU,
metapredict will raise an Exception so you know that you are not
using CUDA as you were expecting.
The default is None, which means we check if there is a
cuda-enabled GPU and, if there is, try to use it. If an int is
passed we use cuda:<int> as the device, where the GPU numbering is
0-indexed (so 0 corresponds to the first GPU). Only set this if you
know which GPU you want to use. Note that MPS is only supported in
PyTorch 2.1 or later, and is still fairly new, so use it at your own
risk.
version : int
Defines the metapredict version to use (must be one of 1, 2
or 3).
show_progress_bar : bool
Flag which, if set to True, means a progress bar is printed as
predictions are made, while if False no progress bar is printed.
Default = True
safe : bool
Flag which, if set to False, means the function overwrites
existing tracks and domains if present. If True, overwriting
will trigger an exception.
Default = True.
Returns
-----------------
None
No return type, but the Protein objects in the Proteome
will be annotated with disordered Domain annotations.
"""
_check_metapredict()
uid2seq = {}
for p in proteome:
uid2seq[p.unique_ID] = p.sequence
# batch predict disorder
D = meta.predict_disorder(uid2seq, device=device, show_progress_bar=show_progress_bar, version=version, return_domains=True, disorder_threshold=disorder_threshold)
for k in uid2seq:
X = D[k]
for boundaries in X.disordered_domain_boundaries:
proteome.protein(k).add_domain(boundaries[0]+1, boundaries[1], name, safe=safe)
if annotate_folded_domains:
for boundaries in X.folded_domain_boundaries:
proteome.protein(k).add_domain(boundaries[0]+1, boundaries[1], folded_domain_name, safe=safe)
## ------------------------------------------------------------------------
##
[docs]
def annotate_proteome_with_disorder_tracks_and_disordered_domains(proteome,
track_name='disorder',
domain_name='IDR',
disorder_threshold=None,
annotate_folded_domains=False,
folded_domain_name = 'FD',
device=None,
version=3,
show_progress_bar=True,
safe=True):
"""
Function that annotates a proteome with disorder Tracks and
disorder Domains for every protein.
By default, disorder Tracks are named 'disoder', although
this can be changed by setting the `track_name` parameter.
By default, disordered Domains are named as 'IDR's, although
this can be changed by setting the `name` parameter.
In addition, if requested, folded domains can also be annotated
as those domains which are not IDRs. These folded domains are
named 'FD's by default, although this can be changed by setting
the `folded_domain_name` parameter.
Disorder prediction uses the batch mode in metapredict, which
leverages parallel predictions automatically on GPUs or CPUs.
However, if a specific device is requested this can be passed
Parameters
-----------------
proteome : shephard.proteome.Proteome
Proteome object to be annotated.
track_name : str
Name of the Track added to each Protein.
Default = 'disorder'
domain_name : str
Name of the Domain added to each Protein.
Default = 'IDR'
disorder_threshold : float
Threshold to be used to define IDRs by the metapredict
domain decomposition algorithm. If set to None (default)
metapredict uses the threshold appropriate for the version
being used, which is what we strongly recommend.
annotate_folded_domains : bool
Flag which, if included, means we ALSO annotate
the regions that are not IDRs as 'FD' (folded
domains), where the name can be changed using
the folded_domain_name variable.
Default = False
folded_domain_name : str
String used to name Folded Domains. Only relevant
if annotate_folded_domains is set to True.
Default = 'FD'
device : int or str
Identifier for the device to be used for predictions.
Possible inputs: 'cpu', 'mps', 'cuda', or an int that corresponds to
the index of a specific cuda-enabled GPU. If 'cuda' is specified and
cuda.is_available() returns False, instead of falling back to CPU,
metapredict will raise an Exception so you know that you are not
using CUDA as you were expecting.
The default is None, which means we check if there is a
cuda-enabled GPU and, if there is, try to use it. If an int is
passed we use cuda:<int> as the device, where the GPU numbering is
0-indexed (so 0 corresponds to the first GPU). Only set this if you
know which GPU you want to use. Note that MPS is only supported in
PyTorch 2.1 or later, and is still fairly new, so use it at your own
risk.
version : int
Defines the metapredict version to use (must be one of 1, 2
or 3).
show_progress_bar : bool
Flag which, if set to True, means a progress bar is printed as
predictions are made, while if False no progress bar is printed.
Default = True
safe : bool
Flag which, if set to False, means the function overwrites
existing tracks and domains if present. If True, overwriting
will trigger an exception.
Default = True.
Returns
-----------------
None
No return type, but the Protein objects in the Proteome
will be annotated with per-residue disorder Tracks and
disordered Domain annotations.
"""
_check_metapredict()
uid2seq = {}
for p in proteome:
uid2seq[p.unique_ID] = p.sequence
# batch predict disorder annotations/scores
D = meta.predict_disorder(uid2seq, device=device, show_progress_bar=show_progress_bar, version=version, return_domains=True, disorder_threshold=disorder_threshold)
# for each unique ID
for k in uid2seq:
# X = DisorderObject
X = D[k]
# cycle through IDR boundaries
for boundaries in X.disordered_domain_boundaries:
proteome.protein(k).add_domain(boundaries[0]+1, boundaries[1], domain_name, safe=safe)
if annotate_folded_domains:
for boundaries in X.folded_domain_boundaries:
proteome.protein(k).add_domain(boundaries[0]+1, boundaries[1], folded_domain_name, safe=safe)
proteome.protein(k).add_track(track_name, values=X.disorder, safe=safe)