org.jscience.biology.taxonomy
Class ItisSupport

java.lang.Object
  org.jscience.biology.taxonomy.ItisSupport

public class ItisSupport
extends java.lang.Object

Provides ITIS query and lookup services for taxonomic information. This includes the ability to search the ITIS*ca database for a string match to a taxon name, which returns the ITIS Taxonomic Serial Number (TSN) for that taxon. One can then use the TSN to query ITIS*ca and find the scientific name, rank, author, synonym taxa, parent taxa, and children taxa (e.g., species within a genus), among other information. See the ItisTaxon class for more on the information that can be retrieved. See: "http://www.cbif.gc.ca/pls/itisca/" for details on the ITIS database.

Here is a brief example of use of the programmatic API:

 String searchPhrase = "Psychotria nervosa";
 try {
   Itis itis = new Itis();
   long newTsn = itis.findTaxonTsn(searchPhrase);
   ItisTaxon newTaxon = itis.getTaxon(newTsn);
   System.out.println("            TSN: " + newTaxon.getTsn());
   System.out.println("Scientific Name: " + newTaxon.getScientificName());
   System.out.println("           Rank: " + newTaxon.getTaxonRank());
   long parentTsn = newTaxon.getParentTsn();
   ItisTaxon parentTaxon = itis.getTaxon(parentTsn);
   System.out.println("     Parent TSN: " + parentTaxon.getTsn());
   System.out.println("Scientific Name: " + parentTaxon.getScientificName());
   System.out.println("           Rank: " + parentTaxon.getTaxonRank());
 

   Vector synonyms = itis.getSynonymTsnList(newTsn);
   for (int i=0; i < synonyms.size(); i++) {
     long synonymTsn = ((Long)synonyms.get(i)).longValue();
     ItisTaxon synonymTaxon = itis.getTaxon(synonymTsn);
     System.out.println("      Synonym TSN: " + synonymTaxon.getTsn());
     System.out.println("  Scientific Name: " +
                                      synonymTaxon.getScientificName());
     System.out.println("             Rank: " + synonymTaxon.getTaxonRank());
   }
 

   Vector children = itis.getChildTsnList(newTsn);
   for (int i=0; i < children.size(); i++) {
     long childTsn = ((Long)children.get(i)).longValue();
     ItisTaxon childTaxon = itis.getTaxon(childTsn);
     System.out.println("        Child TSN: " + childTaxon.getTsn());
     System.out.println("  Scientific Name: " +
                                      childTaxon.getScientificName());
     System.out.println("             Rank: " + childTaxon.getTaxonRank());
   }
 } catch (Exception ie) {
   System.out.println( ie.getMessage());
 }
 

Constructor Summary

ItisSupport()
constructor

Method Summary

long	findTaxonTsn(java.lang.String taxonName) Look up a scientific name in ITIS and get its tsn (taxonomic serial number).
java.util.Vector	getChildTsnList(long tsn) Get an array of the TSN numbers for children of a particular taxon identified by its taxonomic serial number.
long	getParentTsn(long tsn) Get the TSN number for the parent of a taxon which is identified by its own taxonomic serial number.
java.lang.String	getScientificName(long tsn) Retrieve the name of a taxon based on its TSN.
java.util.Vector	getSynonymTsnList(long tsn) Get an array of the TSN numbers for synonyms of a particular taxon identified by its taxonomic serial number.
ItisTaxon	getTaxon(long tsn) Retrieve all of the taxonomic details about a particular taxon identified by its taxonomic serial number.
static void	main(java.lang.String[] args) Main routine for testing

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ItisSupport

public ItisSupport()

constructor

Method Detail

findTaxonTsn

public long findTaxonTsn(java.lang.String taxonName)
                  throws java.lang.Exception

Look up a scientific name in ITIS and get its tsn (taxonomic serial number).

Parameters:

taxonName - the name of the taxon to look up

Returns:

the integer TSN associated with a taxon

Throws:

java.lang.Exception

getTaxon

public ItisTaxon getTaxon(long tsn)
                   throws java.lang.Exception

Retrieve all of the taxonomic details about a particular taxon identified by its taxonomic serial number.

Parameters:

tsn - integer TSN associated with a taxon

Returns:

Taxon a detailed data structure describing a taxon

Throws:

java.lang.Exception

getScientificName

public java.lang.String getScientificName(long tsn)
                                   throws java.lang.Exception

Retrieve the name of a taxon based on its TSN. This is a Utility method that provides the same info as ItisTaxon.getScientificName().

Parameters:

tsn - integer TSN associated with a taxon

Returns:

String the scientific name for this taxon

Throws:

java.lang.Exception

getParentTsn

public long getParentTsn(long tsn)
                  throws java.lang.Exception

Get the TSN number for the parent of a taxon which is identified by its own taxonomic serial number.

Parameters:

tsn - integer TSN associated with a taxon

Returns:

long the TSN of the parent of this taxa

Throws:

java.lang.Exception

getChildTsnList

public java.util.Vector getChildTsnList(long tsn)
                                 throws java.lang.Exception

Get an array of the TSN numbers for children of a particular taxon identified by its taxonomic serial number.

Parameters:

tsn - integer TSN associated with a taxon

Returns:

Vector of Long values that represent the children of this taxon

Throws:

java.lang.Exception

getSynonymTsnList

public java.util.Vector getSynonymTsnList(long tsn)
                                   throws java.lang.Exception

Get an array of the TSN numbers for synonyms of a particular taxon identified by its taxonomic serial number.

Parameters:

tsn - integer TSN associated with a taxon

Returns:

Vector of Long values that represent the synonyms of this taxon

Throws:

java.lang.Exception

main

public static void main(java.lang.String[] args)

Main routine for testing