Site
Sites represent annotations associated with single positions along the sequence. Sites are added to proteins using the Protein.add_site() function, or using functions in the shephard.interfaces.si_sites module.
Sites must have a site type, and can be associated with a symbol (string) and/or a value (numerical, cast to float). Multiple Sites can coexist at the same residue position, which makes Sites well-suited to representing things like post-translational modifications, mutations, or binding sites. Sites also know the position in the sequence they come from and the underlying residue, and can extract Domain and Track information that overlaps the site.
Sites for a given protein can be requested using the protein.site(<site_position>) function. However, it is generally more useful to either request all sites using protein.sites (which returns a list of all sites in the protein) or to request specific sites based on their position, range, type, or some combination of these. Explicit functions for these requests are included in the Protein object. Finally, all sites (or all sites of a specific type) can be requested from an entire proteome using Proteome object functions.
A Site’s value and symbol can be updated in place using update_site_value() and update_site_symbol() (each accepts None to clear the field). Sites can be removed from proteins using the Protein.remove_site() function.
Site properties
- property Site.residue
Returns the amino acid residue associated with the site position as a string.
- property Site.position
Returns the actual sequence indexed position as an int (recall protein indexing starts at 1).
- property Site.protein
Return the Protein object this site is found within
- property Site.site_type
Returns the site type (string)
- property Site.symbol
Returns the symbol associated with this site. Note a symbol is either None or a str type.
- property Site.value
Returns the value associated with this site. Note a value is either None or a float type.
Site update functions
- update_site_value(self, new_value)
Function that updates the site value. Values must be numerical (float) or None.
- Parameters:
new_value (float (or None)) – Updated value
- Returns:
Nothing but sets the value to be the new value
- Return type:
None
- update_site_symbol(self, new_symbol)
Function that updates the site symbol. The symbol must be a string (or None, which clears the symbol).
- Parameters:
new_symbol (str (or None)) – Updated symbol
- Returns:
Nothing but sets the symbol to be the new symbol
- Return type:
None
Site sequence functions
- get_local_sequence_context(self, offset=5)
Returns the local amino acid context around a residue +/- the offset provided.
Note that the offset extends to the start/end of sequence and then silently truncates.
- Parameters:
offset (int) – Defines the +/- region around the position which is used to define the local sequence context.
- Returns:
Returns an amino acid sequence that corresponds to the local sequence context around the site of interest
- Return type:
str
Site Attribute Functions
- property Site.attributes
Provides a list of the keys associated with every attribute associated with this Site.
- Returns:
returns a list of the attribute keys associated with the protein.
- Return type:
list
- Type:
[Property]
- attribute(self, name, safe=True)
Function that returns a specific attribute as defined by the name.
Recall that attributes are name : value pairs, where the ‘value’ can be anything and is user defined. This function will return the value associated with a given name.
- Parameters:
name (str) – The attribute name. A list of valid names can be found by calling the
<Site>.attributes(which returns a list of the valid names)safe (bool (default = True)) – Flag which if true with throw an exception if an attribute with the same name already exists.
- Returns:
Will either return whatever was associated with that attribute (which could be anything) or None if that attribute is missing.
- Return type:
Unknown
- add_attribute(self, name, val, safe=True)
Function that adds an attribute. Note that if safe is true, this function will raise an exception if the attribute is already present. If safe=False, then an existing value will be overwritten.
- Parameters:
name (str) – The parameter name that will be used to identify it
val (<anything>) – An object or primitive we wish to associate with this attribute
safe (bool (default = True)) – Flag which if True with throw an exception if an attribute with the same name already exists, otherwise the newly introduced attribute will overwrite the previous one.
- Return type:
None - but adds an attribute to the calling object
- remove_attribute(self, name, safe=True)
Function that removes a given attribute from the Site based on the passed attribute name. If the passed attribute does not exist or is not associate with the Site then this will trigger an exception unless safe=False.
- Parameters:
name (str) – The attribute name that will be used to identify it
safe (bool (default = True)) – Flag which if True with throw an exception if an attribute this name does not exists. If set to False then if an attribute is not found it is simply ignored
- Returns:
No return type but will remove an attribute from the protein if present.
- Return type:
None
Site Domain Functions
- get_domains(self, offset=0, safe=True)
Function that returns the set of domains that the site lies within. The oofset parameter defines the wiggle room +/- that is tolerated, but defaults to 0.
- Parameters:
offset (int (default = 0)) – +/- values around the site from which regions are taken.
safe (bool (default = True)) – If set to True, missing tracks trigger an exception, else they just return None.
- Returns:
Returns a list of domain objects for which this site can be found in or near
- Return type:
list
Site Track Functions
- get_track_values(self, name, offset=0, safe=True)
Function that returns the region of a protein’s values- track associated with this site, +/- some offset.
If the track name is missing and safe is True, this will throw an exception, otherwise (if safe=False) then if the track is missing the function returns None.
- Parameters:
name (str) – Track name
offset (int (default = 0)) – +/- values around the site from which regions are taken
safe (bool (default = True)) – If set to True, missing tracks trigger an exception, else they just return None
- Returns:
Returns a list of floats that corresponds to the set of residues associated with the domain of interest
- Return type:
list
- get_track_value(self, name, safe=True)
Function that returns the value associated with the track at the residue position associated with this site.
If the track name is missing and safe is True, this will throw an exception, otherwise (if safe=False) then if the track is missing the function returns None.
- Parameters:
name (str) – Track name
safe (bool (default = True)) – If set to True, missing tracks trigger an exception, else they just return None
- Returns:
Returns the value associated with the track of interest at this site.
- Return type:
float or int
- get_track_symbols(self, name, offset=0, safe=True)
Function that returns the region of a protein’s symbols track associated with this site.
If a Track of this name is not associated with the underlying protein and safe is True, this will throw an exception, otherwise (if safe=False) then if the track is missing the function returns None.
- Parameters:
name (str) – Track name
offset (int (default = 0)) – +/- values around the site from which regions are taken
safe (bool (default = True)) – If set to True, missing tracks trigger an exception, else they just return None
- Returns:
Returns a list of strs that corresponds to the set of residues associated with the domain of interest.
- Return type:
list
- get_track_symbol(self, name, safe=True)
Function that returns the symbol associated with the track at the residue position associated with this site.
If a Track of this name is not associated with the underlying protein and safe is True, this will throw an exception, otherwise (if safe=False) then if the track is missing the function returns None.
- Parameters:
name (str) – Track name
safe (bool (default = True)) – If set to True, missing tracks trigger an exception, else they just return None
- Returns:
Returns the string associated with the symbol at this site
- Return type:
str