BioSitemap and BRO Java API

Developers can use biositemaps available on the World-Wide Web to aggregate the information about biomedical resources. Developers can query for resources specified in a biositemap, aggregate resources from different biositemaps and store them in their own RDF database, explore the properties of the resources (such as authors, descriptions, urls, organizations, keywords, etc.), and find resources of specific types. Developers can also use the hierarchy of resource types defined in the BRO to search for resources specifying a more general type. For instance, one can search for all Image_Processing resources and get resources that are tagged with specific Image_Processing resource types, such as Atlas_Generation, Cortical_Modeling, Segementation, and others (all subclasses of Image_Processing in BRO).

This brief user guide presents a Java API for easily creating, reading, editing biositemaps from inside a Java applications. This guide discusses the following topics:

If you already using the BioSitemaps API you may be interested in visiting the javadoc of the BioSitemaps-API.

This guide tries to be self explanatory. In case that after you went through the guide and followed the instructions carefully you still have questions or feedback about the API please write to biositemaps@biositemaps.org and we will try to help you in a timely manner.

Services for querying the BRO Ontology

NCBO REST Services are available for querying the BRO (ontology id #1104). Services include queries to find a specific version of an ontology or list all ontology categories.

Download and Installation Instructions

First, download the API, dependent jar files and example source at biositemaps.zip and unzip to create a biositemaps-api directory. The latest Biomedical Resource Ontology should also be downloaded into the same directory.

The following command executed in the extracted directory will compile example code that is using the API to create a simple biositemap called Test_biositemap.rdf (requires Apache Ant).


	 ant build
	 

Instructions for biositemap creation and editing

The following command executed in the extracted directory will execute example code that is using the API to create a simple biositemap called Test_biositemap.rdf (requires Apache Ant).


	 ant execSimple
	 

We explain the steps of creation of a new biositemap in the following example code (download at complete source at biositemaps.zip).

	

try {
	
	// --- create a new BioSitemap ---
	BioSitemap bsm = BioSitemap.create("Test_biositemap.rdf");
	//BioSitemap bsm = BioSitemap.createWithRelativeFolderRepository("test.rdf", ".");
	//BioSitemap bsm = BioSitemap.createWithRepository("test.rdf", new LocalFileRepository(new File("BiomedicalResourceOntology_v20.owl")));

	// --- create a named ResourceDescription in the biositemap ---
	ResourceDescription rs = bsm.createResourceDescription("Protege");

	// --- set simple (String) properties of the ResourceDescription 
	rs.setResourceName("Protégé");
	rs.setDescription("An ontology authoring tool");
	rs.setURL("http://protege.stanford.edu/");
	rs.setOrganization("NCBO");
	rs.setLicense("Mozilla");
	//set multiple properties with setXXX and addXXX
	rs.setAuthors("Ray Fergerson");
	rs.addAuthors("Tania Tudorache");
	rs.addAuthors("Timothy Redmond");
	rs.addAuthors("Jennifer Vendetti");
	//set multiple properties as a list
	rs.setKeywords(Arrays.asList(new String[]{"Ontology", "Editor", "Protege"}));
	
	// --- set instance properties of the ResourceDescription
	rs.addResourceType(bsm.createResource("BRO:Ontology_Development_and_Management"));
	//in future versions we recommend using: 
	//rs.setResourceType(BRO_Ontology_Development_and_Management.class);
	
	VersionInformation ver = bsm.createVersionInformation();
	ver.setVersion("3.3.1");
	ver.setReleaseDate("Aug 24, 2007");
	ver.setDevelopmentStage("Production");
	rs.setVersionInformation(ver);

	// --- save the BioSitemap file to disk ---
	bsm.save();
	
} catch (BioSitemapException e) {
	e.printStackTrace();
}
   

The green colored comments in the above example code explain each step of the process of creating a new biositemap: creating the file, creating new resource description(s) in it, editing the properties of those resource descriptions and finally saving it to the disk. A detailed description of each method is provided in the javadoc documentation of the BioSitemaps-API.

Instructions for opening and editing existing biositmaps

The following command executed in the extracted directory will execute example code that is using the API to create a simple biositemap called Test_biositemap.rdf (requires Apache Ant).


	 ant execAdvanced
	 

The following example code shows how can one open an existing biositemap, read and modify its content and finally save it to the disk: (download at complete source at biositemaps.zip).

	

String BRO = BioSitemap.BRO_NAMESPACE;

try {

	// --- open existing biositemap ---
	BioSitemap bsm = BioSitemap.open("Test_biositemap.rdf", false);
	//BioSitemap bsm = BioSitemap.openWithRelativeFolderRepository("test.rdf", ".", false);
	//BioSitemap bsm = BioSitemap.openWithRepository("test.rdf", new RelativeFileRepository(new File("./BiomedicalResourceOntology_v20.owl"), "BiomedicalResourceOntology_v20.owl", true), true);
	
	// --- print out the existing resource descriptions contained in the biositemap ---
	System.out.println("\nInitial biositemap content:");
	for (ResourceDescription resDesc : bsm.getAllResourceDescriptions()) {
		System.out.println(resDesc);
	}
	
	// --- testing for the existence of a specific ResourceDescription ---
	if (bsm.hasResourceDescription("Protege")) {
		// --- getting existing ResourceDescription ---
		ResourceDescription rs = bsm.getResourceDescription("Protege");

		// --- setting and adding new property values ---
		rs.setPlatforms("Platform independent (Java VM)");
		VersionInformation verInfo = bsm.createVersionInformation();
		verInfo.setVersion("3.4 Beta - Build 504");
		verInfo.setReleaseDate("June 24, 2008");
		verInfo.setDevelopmentStage("Beta");
		rs.addVersionInformation(verInfo);
	}
	else {
		System.out.println("Resource Description \"Protege\" could not be found");
	}
	
	
	// --- create a new ResourceDescription in the same biositemap --- 
	ResourceDescription rs = bsm.createResourceDescription("Jambalaya");
	
	// --- set resource_type ---
	rs.setResourceType(BRO + "Ontology_Visualization");
	// the previous command is a short form for doing: 
	//rs.setResourceType(bsm.createResource(BRO + "Ontology_Visualization"));
	
	// --- set some common properties by usig the setXXX/addXXX methods ---
	rs.setResourceName("Jambalaya");
	rs.addOrganization("NCBO");
	rs.setDescription("A tool for visualizing ontologies");
	rs.addURL("http://www.thechiselgroup.org/jambalaya");
	rs.addAuthors("Chris Callendar");
	rs.setLicense("Open source");
	rs.setKeywords("ontologies, visualization");

	// --- demonstration of how adding additional properties and removing existing ones works---
	rs.addURL("www.google.com");
	rs.removeURL("www.google.com");
	//this URL won't appear in the final result

	// --- add some more advanced properties: area_of_application, biological_concept, funding_source, etc. ---
	rs.addFundingSource(bsm.createFundingSource("BRO:Heterogeneous_Funding_Resource"));
	//in future versions we recommend using: 
	//rs.addFundingSource(bsm.createFundingSource(BRO_Heterogeneous_Funding_Resource.class));

	
	// --- print out the existing resource descriptions contained in the biositemap ---
	System.out.println("\n\nFinal biositemap content (all Resource Description)):");
	for (ResourceDescription resDesc : bsm.getAllResourceDescriptions()) {
		System.out.println(resDesc);
	}
	
	// --- call utility methods to get list of all instances of specific type in a biositemap ---
	System.out.println();
	System.out.println("List of all VersionInnformation instances: " + bsm.getAllVersionInformationInstances());
	System.out.println("List of all Resource instances of type BRO:Software: " + bsm.getAllResourceInstancesOfType(BRO + "Software"));

	// --- save the modified BioSitemap file to disk ---
	bsm.save();

} catch (BioSitemapException e) {
	e.printStackTrace();
}
   

The green colored comments in the above example code explain each step of the process of working with existing biositemaps: opening the file, getting the existing resource descriptions contained in it, creating new resource descriptions, creating, modifying and deleting the properties of the new or existing resource descriptions and finally saving it to the disk. A detailed description of each method is provided in the javadoc documentation of the BioSitemaps-API. Source is available at https://bmir-gforge.stanford.edu/gf/project/biositemaps/scmsvn/ (see Access Info for instructions).