JParts API

Project Description

This API provides methods to retrieve models of, and metadata about, biological parts. Two main classes in this API are PartsHandler and ModelBuilder. PartsHandler is used to retrieve data from the Virtual Parts repository while the latter is used to create simulateable models using models retrieved from the repository.

Currently, the repository is located at
Click here to download the API.
Click here to download the API and its dependencies.


Retrieving Parts

Metadata about a part is represented with the Part class. PartsHandler provides methods to get a Part object based on its ID using the GetPart method:

PartsHandler partsHandler = new PartsHandler(“”);
Part part= partsHandler.GetPart(“PspaRK”));

List of parts can also be retrieved using the PartsHandler’s GetParts method. Due to the large number of parts, it is not possible to get information about all the parts at once, and therefore a method called paging is used. Only 50 records can be retrieved at each method call. For example, the code below retrieves the first 50 parts from the repository:

Parts parts=partsHandler.GetParts(1);

The GetPartsSummary method of the PartsHandler can be used to get the number of total pages in the repository in order to iteratively retrieve all records. The method returns a Summary object including the total number of pages, with each page having 50 records:

Summary summary=partsHandler.GetPartsSummary();

The number of pages can then be used to iteratively access all of the parts from the repository:

Summary summary=handler.GetPartsSummary();
int pageCount=summary.PageCount;
Parts allParts=new Parts();
for (int i=1;i<=pageCount;i++)
Parts parts=handler.GetParts(i);

The repository includes hundreds of parts and therefore retrieving all parts may not be efficient. Once the parts are retrieved, they can easily be saved locally using the Serializer class. This class provides methods to serialize/deserialize a list of parts into/from a String variable. The example below demonstrates how to save information about parts to a local file and use this file to create a List<Part> object, which includes the list Part objects.

Serializer serializer = new Serializer();
String content = serializer.SerializeParts(parts);
Serializer.WriteToFile(“c:/temp/parts.txt”, content);
File file = new File(“c:/temp/parts.txt”);
String savedContent = Serializer.GetFileContent(file);
Parts savedParts = serializer.GetParts(savedcontent);

Parts can also be retrieved based on their type and other additional features. Similarly the summary information can be returned using the same criteria being used. For example, to get information about promoters the following lines can be used in order to initially get the number of pages for promoters and filter the parts to retrieve information only about promoter parts:

Summary summary=handler.GetPartsSummary(“Promoter”);
Parts parts=handler.GetParts(1,”Promoter”);

Furthermore, parts have subtypes. For example, a promoter virtual part can have subtypes to indicate the promoter’s sigma factor, and whether or not the promoter is inducible. These subtypes are listed on the left-hand side of the Virtual Parts website for pages relevant to part types. For promoter type of parts, link can be used to see these subtypes. BO_SigAPromoter and BO_InduciblePromoter are respectively used to find SigA and inducible promoters. These subtypes are stored as key/value pairs in the metadata of a part and can also be used to search for parts. The following example retrieves the list of SigA promoters.

Parts parts = handler.GetParts(1, “Promoter”, “type”, “BO_SigAPromoter”);

Summary information for SigA promoters can similarly be retrieved as described above using a different method call.

Summary summary = handler.GetPartsSummary(“Promoter”, “type”, “BO_SigAPromoter”);

While key/value pairs can be ‘type’ and corrresponding type values, they can also be GO terms in the form of ‘located_in’/GO_TERM_ID or ‘has_function’/GO_TERM_ID key/value pairs.

Retrieving Parts by Parameters

Parts can further be retrieved based on parameter values. The searching of parts using parameter values requires the use of Filter objects which can be constructed using the following filter operators:


Filters are constructed using the type of parameter to search for, the filter operator and the value specified for the parameter. For example, in order to retrieve all the parts whose transcription rates are greater than 0.5, the following Filter object can be constructed:

Filter greaterThanFilter=new Filter(FilterParameter.TRANSCRIPTION_RATE, FilterOperator.GREATER_THAN, “0.5”);

Any two Filter obejcts can be combined in a query by constructing an ANDFilter which implements the logical conjuction specified in the given Filter objects. For example, ANDFilter can be used to search for a range of parameter values. The example below is used to construct a filter which can then be used to search for promoters with transcription rates greater than 0.5 and smaller than 0.6.

Filter greaterThanFilter=new Filter(FilterParameter.TRANSCRIPTION_RATE, FilterOperator.GREATER_THAN_OR_EQUAL_TO, “0.5”);
Filter lessThanFilter=new Filter(FilterParameter.TRANSCRIPTION_RATE, FilterOperator.LESS_THAN_OR_EQUAL_TO, “0.6”);
ANDFilter andFilter=new ANDFilter(filter1, filter2);

Filter and ANDFilter objects implements the IFilter interface and can be used to call GetParts method of the PartsHandler to retrieve parts.

Parts parts=handler.GetParts(andFilter);


Retrieving Interactions

The Virtual Parts repository also stores metadata about interactions, including the types of interactions, participating parts and reaction stoichiometries. Information about these interactions can be accessed using the GetInteractions method:

Interactions interactions=handler.GetInteractions(part);

Retrieving models of parts and interactions

In addition to metadata, parts and interactions are also represented using SBML models. Each part or interaction has a single model with defined inputs and outputs. PartsHandler’s GetModel and GetInteractionModel methods are respectively used to retrieve models of parts and interactions as Java objects:

SBMLDocument sbmlDocument=handler.GetModel(part);
SBMLDocument sbmlDocument=handler.GetInteractionModel(interaction);

In addition, to retrieving models of parts and interactions from the repository, the API also allows constructing these models at runtime using object representation of Parts and Interactions. Models of parts encapsulate part specific interactions that are called internal interactions. These interactions are not dependent on other parts are usually represent biochemical reactions such as degradation and autodephosphorylation. The values of stoichometries and biochemical parameters of biological molecules can be respectively updated using the InteractionPartDetail and Parameter objects of a corresponding interaction object. Therefore, models of biological parts that do not exist in the repository can also be created.

List spaKInternalInteractions=partsHandler.GetInternalInteractions(spaKPart).getInteractions();
// Now, change the properties in Part and Interaction objects. Interaction object has a list of parameters and details of parts included in that interaction.
SBMLDocument proteinSpaK=partsHandler.CreatePartModel(spaKPart, spaKInternalInteractions);

Similarly, models of interactions can be constructed at runtime:

Interaction spaK_spaR_interactionObject=partsHandler.GetInteractions(spaKPart).getInteractions().get(0);
//Change the properties in the Interaction object
SBMLDocument spaK_spaR_interaction=partsHandler.CreateInteractionModel(spaK_spaR_interactionObject);


Models of parts and interactions are not simulateable on their own. However, these models can be joined together using their inputs and outputs to create models of systems. ModelBuilder provides methods to add the models of parts and interactions into an empty container model and to connect them in order to construct simulateable models. This class is initialized using an SBML container model, which can be created using the SBMLHandler classes’s GetSBMLTemplateModel method:

SBMLHandler sbmlHandler = new SBMLHandler();
SBMLDocument sbmlContainer=sbmlHandler.GetSBMLTemplateModel(“SubtilinReceiver”);

The ModelBuilder class uses model annotations in order to connect models of parts and interactions using their inputs and outputs. Only the models that have the same type of input and output can be connected. For example promoter-mRNA, mRNA-RBS, RBS-CDS connections would be valid since models of these parts would have compatible inputs and outputs such as mRNA, PoPS and RiPS. The following example shows how to add and connect ‘RBS_SpaK’ RBS and ‘SpaK’ and CDS parts to a container model using the Add and Link methods.

ModelBuilder modelBuilder = new ModelBuilder(sbmlContainer);
SBMLDocument rbsSpaK=partsHandler.GetModel(partsHandler.GetPart(“RBS_SpaK”));
SBMLDocument proteinSpaK=partsHandler.GetModel(partsHandler.GetPart(“SpaK”));

The repository also provides models for mRNAs which have the constant ‘mRNA’ IDs. However, each time when an mRNA model is requested, the repository returns such a model using different internal IDs and hence mRNA models can be used more than once in the same container model. Moreover, although interactions between CDS parts do not need to be connected explicitly, any interaction involving a promoter also needs to be connected using the ModelBuilder class. For example, the output of a promoter can be connected to the input of such an interaction and the interaction’s output can be connected to an mRNA model. Such connections are also carried out using the Link method of the ModelBuilder class.

The example below shows the construction of the subtilin receiver model which can be simulated. Subtilin receiver includes a two component systems comprising the SpaK kinase and the SpaR reponse regulators. Coding sequences of these proteins are located in the same operon and are expressed constitutively by the pspaRK promoter.

Subtilin Receiver

SpaK is activated by Subtilin via phosphorylation and upon activation phosphorylates SpaR. The activated SpaR acts as a transcription factor to induce the pspaS promoter in order to express green fluorescent protein.

SBMLHandler sbmlHandler = new SBMLHandler();
SBMLDocument sbmlContainer=sbmlHandler.GetSBMLTemplateModel(“SubtilinReceiver”);
ModelBuilder modelBuilder = new ModelBuilder(sbmlContainer);
PartsHandler partsHandler = new PartsHandler(serverURL);
SBMLDocument pspaRK = partsHandler.GetModel(partsHandler.GetPart(“PspaRK”));
SBMLDocument rbsSpaK=partsHandler.GetModel(partsHandler.GetPart(“RBS_SpaK”));
SBMLDocument rbsSpaR=partsHandler.GetModel(partsHandler.GetPart(“RBS_SpaR”));
Part spaKPart=partsHandler.GetPart(“SpaK”);
SBMLDocument proteinSpaK=partsHandler.GetModel(spaKPart);
SBMLDocument proteinSpaR=partsHandler.GetModel(partsHandler.GetPart(“SpaR”));
SBMLDocument spaK_spaR_interaction= partsHandler.GetInteractionModel(partsHandler.GetInteractions(spaKPart).getInteractions().get(0));
Part pspaSPart=partsHandler.GetPart(“PspaS”);
SBMLDocument pspaS=partsHandler.GetModel(pspaSPart);
SBMLDocument pspaS_SpaR_interaction= partsHandler.GetInteractionModel(partsHandler.GetInteractions(pspaSPart).getInteractions().get(0));
SBMLDocument rbsGFP=partsHandler.GetModel(partsHandler.GetPart(“RBS_SpaS”));
SBMLDocument proteinGFP=partsHandler.GetModel(partsHandler.GetPart(“GFP_rrnb”));
//Get mRNAs.mRNA virtual part is a template. Each time it is given with different IDs
SBMLDocument mRNASpaRK = partsHandler.GetModel(partsHandler.GetPart(“mRNA”));
SBMLDocument mRNAGFP = partsHandler.GetModel(partsHandler.GetPart(“mRNA”));
modelBuilder.Link(pspaRK, mRNASpaRK);
String sbmlOutput = modelBuilder.GetModelString();
Serializer.WriteToFile(“C:/subtilinreceiver.xml”, sbmlOutput);

The example subtilin receiver device model shows the use of parts only once in order to build a simulateable model. Each modelling entity in a part model contains a unique ID that should also be unique when used to build a model of a system. Therefore, for subsequent use of a model, the model must be cloned with different IDs for modelling entities. ModelBuilder class also provides methods to clone models and interactions. The following example shows the cloning of pspaS1 promoter model as pspaS2, and pspaS_SpaR_interaction1 interaction model as pspaS_SpaR_interaction2:

SBMLDocument pspaS2=modelBuilder.Clone(pspaS1, pspaSPart);
SBMLDocument pspaS_SpaR_interaction2=modelBuilder.CloneInteraction(pspaS_SpaR_interaction1, pspaSInteraction);