PHENSIM User Manual
Introduction
PHENSIM is a software developed to simulate the de-regulation of elements on pathways. The tool, available as a web application, provides a convenient GUI for submitting and displaying simulations, and APIs for submitting batch jobs. The features offered by the two interfaces are almost identical.
To obtain reliable results, simulated nodes should be statistically independent. That is, in each pathway no directed paths connecting such nodes should be present. However, this limitation can be overcome by enriching pathways with a dummy element linking the each dependent node. The simulation can be performed on the dummy element, avoiding the need for statistical independence.
Registration is needed to identify each request, and avoid SPAM. After registration, no limitations are applied to the users. Any submission is kept private, and no other user can view it.
All elements within pathways are identified using the following accession numbers:
- Entrez Id for genes (eg 7157 for TP53);
- miRBase mature Id for miRNAs (eg hsa-let-7f-5p);
- KEGG Identifiers for other elements (eg cpd:C00047 for Lysine acid).
Below a detailed description on the main parts of the web interface is given. For APIs, see the following link.
User Panel
The User Panel is the main page from which an user can access all services provided by PHENSIM. From the page, the user can:
- submit new simulations by choosing an activity from the Analysis panel on the left,
- get a list of all previously submitted simulations,
- and create new authentication keys for APIs.
The Analysis History panel displays a list of all previously submitted simulation. For each submission, its type, state and insertion date are reported. For each simulation, the user can check its log ( button), view its results ( button), or delete it ( button). A job can be deleted unless it is being processed by our system. In such a case, the user will have to wait for completion.
All analysis are kept in our system for one year after its completion.
The Your API Tokens panel is employed to generate authentication keys for the API interface. More details are available here. The button at the top of the panel adds new token. The token will only be displayed once. The user must therefore take note of its value and keep it in a safe place as it allows access to all his submission.
Simple Simulation Form
This form can be employed to submit new simulations on elements already within pathways (genes, microRNAs, or metabolites) through a simplified wizard. The user first specifies the organism. Than he may choose one or more over-expressed nodes, and/or one or more under-expressed nodes, and zero or more non-expressed nodes.
The simulation is ready to be submitted as it is. However, in the last wizard panel some advanced parameters can be altered to better suit the needs of the user:
- Epsilon: A range around zero within which a node is considered non-expressed;
- RNG seed: an integer number used as seed for the random number generator (specify only to ensure perfect reproducibility of the results);
- Enrich pathways with miRNAs: select to enable automatic addition of miRNAs in pathways;
- Compute simulations on the meta-pathway: activate to perform the simulation on the meta-pathway obtained by merging all biological pathways of the organism (More details in Alaimo et al., 2017). If your wish to simulate the impact on one or more pathway in isolation, deselect this option.
Advanced Simulation Form
The advanced simulation form allows users to perform simulations by manually specifying all parameters in the format required by PHENSIM. Although more complex, this feature offers greater flexibility than the previous one. Indeed, the user can upload a database for custom pathway enrichment (adding items such as drugs, exogenous elements, vesicles, exosomes, or other elements for which the user knows interactions with genes within pathways). The database can be used entirely, or filtered through the Optional Db Filter field. New types of nodes and edges can also be added by providing specific enrichment files.
More details on the input files are available below.
All other parameters are identical to those in the simplified submission form.
Simulation Parameters File
The simulation parameter file specifies the list of deregulations to be simulated. It is tab-separated textual file, where each line specifies the identifier of a node together with type of deregulation (OVEREXPRESSION, UNDEREXPRESSION).
Example of Simulation Parameters File
7157 OVEREXPRESSION 2475 UNDEREXPRESSION hsa-miR-7-5p OVEREXPRESSION
Enrichment Database File
The enrichment database file is a tab-separated text file that contains a row for each edge that could be added to pathways.
Each row should be divided in 9 fields:
- source node id: an arbitrarily chosen identifier which is used to uniquely represent the new node;
- source node name: a name displayed to the user;
- source node type: a type for the node (use one from below or specify custom ones using the appropriate file);
- destination node id: an identifier for the destination node (it must be already present in the pathway);
- destination node name: a name for the destination node (can be empty);
- destination node type: a type for the destination node (can be empty);
- edge type: the type of edge that will be added to the pathway;
- edge subtype: the subtype of the edge that will be added to the pathway (the subtype represents the type of action that the source node has on the destination node, i.e. activation, inhibition);
- optional filter: a string that can be used in the Optional Db Filter field to select only some parts of the file.
In order for the enrichment process to be successful, the destination node must be already within the pathway. If the destination node is not found, the edge will not be added. The source node can be absent. It will be automatically created in the enrichment phase. The following is an example of enrichment file.
VES1 Vescicle 1 VESCICLE 7157 TP53 GENE VESCICLE_EDGE ACTIVATION Vescicle1 VES1 Vescicle 1 VESCICLE 2475 MTOR GENE VESCICLE_EDGE INHIBITION Vescicle1 VES1 Vescicle 1 VESCICLE hsa-miR-7-5p MIRNA VESCICLE_EDGE INHIBITION Vescicle1 VES2 Vescicle 2 VESCICLE hsa-let-7e-5p MIRNA VESCICLE_EDGE INHIBITION Vescicle2 VES2 Vescicle 2 VESCICLE hsa-miR-21-3p MIRNA VESCICLE_EDGE ACTIVATION Vescicle2 VES2 Vescicle 2 VESCICLE 57527 RPTOR GENE VESCICLE_EDGE ACTIVATION Vescicle2
The previous sample file contains two different vescicles. To enrich each pathway with the edges of the first vescicle, the user can specify Vescicle1 in the Optional Db Filter field of the Advanced Simulation form.
Custom Node Type File
The custom node type file is an optional tab-separated text file where each row represents a new node type. Each node type consists of a name and a sign used for the computation of pathway accumulator. The sign represents the action of such type of elements on the whole pathway. If they tend to activate the pathway the sign will be positive, negative otherwise.
Example:
VESCICLE +1 DRUG -1
Custom Edge Type File
The custom edge type file is an optional tab-separated text file where each row represents a new edge type. Only the name of the edge type is needed. The edge subtype represents the action undertaken by the edge.
Example:
VESCICLE_EDGE DRUG_EDGE
Custom Edge SubTypes File
The custom edge subtypes file is an optional tab-separated text file where each row represents a new edge subtype. The edge subtype explain the effect that the source node has on the target node (eg activation or inhibition), ad is fundamental for the correct computation of PHENSIM activity score.
Each row in the enrichment file has 2 fields: the name of the subtype, a weight used to represent the effect (+1 activation, -1 inhibition, 0 no effect).
An optional third field might be specified. The third field represents the priority of the edge when merging pathways.
Example:
VESCICLE_CONTAINS 0 VESCICLE_ACTIVATE +1 VESCICLE_INHIBIT -1 DRUG_INHIBIT -1
Default Node Types
GENE | A gene identified by Entrez Id |
COMPOUND | A compound identified by KEGG Id |
MAP | A pathway identified by KEGG Id |
REACTION | A reaction identified by KEGG Id |
MIRNA | A miRNA identified by miRBase mature Id |
ENZYME | An enzyme identified by KEGG Id or Entrez Id, if available |
Default Edge Types
ECREL | enzyme-enzyme relation, indicating two enzymes catalyzing successive reaction steps |
PPREL | protein-protein interaction, such as binding and modification |
GEREL | gene expression interaction, indicating relation of transcription factor and target gene product |
PCREL | protein-compound interaction |
MGREL | miRNA-gene interaction |
REACTION | a reaction between substrates that produce a specific product |
Default Edge Subtypes
COMPOUND | Some chemical compound interaction |
REACTION_SUBSTRATE | The substrate of a reaction |
REACTION_PRODUCT | The product of a reaction |
ACTIVATION | A positive effects which may be associated with molecular binding |
INHIBITION | A negative effects which may be associated with molecular binding |
EXPRESSION | Activation via DNA binding |
REPRESSION | Inhibition via DNA binding |
MIRNA_INHIBITION | A miRNA-mRNA inhibition interaction |
TFMIRNA_ACTIVATION | A transcription factor which activates miRNA transcription |
TFMIRNA_INHIBITION | A transcription factor which inhibits miRNA transcription |