org.jscience.biology.taxonomy
Class ItisSupport

java.lang.Object
  extended by 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