Track
Tracks represent annotations associated with the full length of the protein (i.e. per-residue sequence annotations). Tracks are added to proteins using the Protein.add_track() function, built on-the-fly from the sequence with Protein.build_track_values_from_sequence() / Protein.build_track_symbols_from_sequence(), or read in using functions in the shephard.interfaces.si_tracks module.
A Track must have a track name, and is either a values track (a per-residue vector of numbers, cast to float) or a symbols track (a per-residue list/string of symbols) — never both. A Track has a strict one-to-one mapping with the protein sequence: SHEPHARD validates at construction time that the number of values/symbols exactly matches the protein length, and that a given track name is consistently a values track or a symbols track across the whole Proteome.
Tracks are appropriate when an analysis produces a continuous output that can be projected along the sequence (e.g. a disorder score, a hydropathy window, an AlphaFold pLDDT). If, instead, your analysis reveals discrete regions or individual positions, Domain or Site annotations are more appropriate, respectively.
Tracks for a given protein can be requested using the protein.track(<track name>) function (returns the Track object), or the underlying data accessed directly with protein.get_track_values() / protein.get_track_symbols(). Sub-regions can be extracted with values_region() / symbols_region(), and individual positions with value() / symbol(). All tracks of a given name across an entire proteome can be requested with Proteome.get_tracks_by_name().
Like every other SHEPHARD annotation, a Track can carry arbitrary key-value attributes, either passed at creation (Protein.add_track(..., attributes={...})) or added later with Track.add_attribute(). Note that Track attributes live in memory only — they are not written to or read from SHEPHARD Tracks files (see SHEPHARD files), although they are preserved when Proteins are copied into a new Proteome.
Tracks can be removed from proteins using the Protein.remove_track() function.
Track Properties
- property Track.name
Returns the track name
- Type:
[Property]
- property Track.values
Returns a list that matches the complete set of values for this track. If no values are assigned returns None
- Type:
[Property]
- property Track.symbols
Returns a list that matches the complete set of symbols for this track. If no symbols are assigned returns None
- Type:
[Property]
- property Track.protein
Returns the Protein that this Track is associated with
- Type:
[Property]
- property Track.track_type
Returns the track type. Will always be one of ‘values’ or ‘symbols’.
- Type:
[Property]
Track Functions
- symbol(self, position, safe=True)
Returns a single symbol from the passed position.
- Parameters:
position (int) – Starting position of interest.
safe (bool (default = True)) – Flag which if true with throw an exception if a symbol is requested from a symbol track.
- Returns:
Returns a symbol associated with the passed position
- Return type:
str
- value(self, position, safe=True)
Returns a single value from the passed position.
- Parameters:
position (int) – Starting position of interest.
safe (bool (default = True)) – Flag which if true with throw an exception if a value is requested from a symbol track.
- Returns:
Returns a value associated with the passed position
- Return type:
float
- symbols_region(self, start, end=None)
Returns a single symbol or a subregion of symbols, depending on if a start and end position are provided or just a start position.
- Parameters:
start (int) – Starting position of interest.
end (int) – Ending position of interest. If not provided then only the symbol at the start position is returned.
- Returns:
Returns a list of values that maps to the residues in the intervening region defined by start and end).
- Return type:
list
- values_region(self, start, end=None)
Returns a single value or a subregion of values, depending on if a start and end position are provided or just a start position
- Parameters:
start (int) – Starting position of interest
end (int) – Ending position of interest. If not provided then only the value at the start position is returned.
- Returns:
Returns a list of values that maps to the residues in the intervening region defined by start and end)
- Return type:
list
Track Attribute Functions
- property Track.attributes
Provides a list of the keys associated with every attribute associated with this Track.
- 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.
NOTE: Track attributes cannot be loaded or saved to file when Tracks are read/written via interfaces.si_track.
- Parameters:
name (str) – The attribute name. A list of valid names can be found by calling the
<Track>.attributes(which returns a list of the valid names).
- safebool (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.
NOTE: Track attributes cannot be loaded or saved to file when Tracks are read/written via interfaces.si_track.
- 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 Track based on the passed attribute name. If the passed attribute does not exist or is not associate with the Track then this will trigger an exception unless safe=False.
- Parameters:
name (str) – The parameter 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