Skip to main content
Jump to: navigation, search

Difference between revisions of "Welcome STEM Developers"

 
m (STEM Installation Instructions)
Line 38: Line 38:
 
#Obtain the source code for the STEM project from the CVS repository.  [?]
 
#Obtain the source code for the STEM project from the CVS repository.  [?]
  
==STEM Installation Instructions==
+
=STEM Installation Instructions=
===Installing  Java™ 5 JVM===
+
==Installing  Java™ 5 JVM==
 
STEM requires Java Version 1.5.
 
STEM requires Java Version 1.5.
 
IBMers should obtain the IBM version of Java 1.5.  Others can use either IBM's Java 1.5 or the Sun Java 1.5 [[http://java.sun.com/j2se/1.5.0/download.jsp]].
 
IBMers should obtain the IBM version of Java 1.5.  Others can use either IBM's Java 1.5 or the Sun Java 1.5 [[http://java.sun.com/j2se/1.5.0/download.jsp]].
Line 49: Line 49:
 
*Run the installation program by double clicking on the file.
 
*Run the installation program by double clicking on the file.
  
===Installing the Eclipse Environment===
+
==Installing the Eclipse Environment==
  
 
Goto [[STEM Eclipse Setup]]
 
Goto [[STEM Eclipse Setup]]
  
===Running Stem as a standalone application===
+
==Running Stem as a standalone application==
 
If you want to first tryout STEM as an application then we provide a standalone version of STEM that only requires that you have Java 1.5 or higher installed.  
 
If you want to first tryout STEM as an application then we provide a standalone version of STEM that only requires that you have Java 1.5 or higher installed.  
  

Revision as of 23:05, 31 January 2007

Introduction

This article is intended to be the starting point for developers working on the Spatio-Temporal Epidemiological Modeler Project (STEM) code base. It contains a detailed description of how the project is organized, how to find all of the resources associated with the project, and how to install, configure and use the necessary development environment.

One of the advantages of this document is that it gets newcomers “up and running” faster and it allows them to contribute to the project immediately by correcting any inaccuracies or omissions the document contains or by clarifying any descriptions. As a newcomer to the project you have a totally unique and extremely valuable perspective, if you can't find something or it doesn't make sense to you then you're probably not alone. When you find out the answer to your quandary, please record it here so those that come after you can “stand on your shoulders”. Welcome aboard!

The STEM code base is written in Java Version 5 and is organized as a set of well defined components using the eclipse (www.eclipse.org) plug-in tool framework. The components are integrated through a well defined “extension point” mechanism that makes the entire code base highly extensible. The use of the eclipse framework also provides for multi-platform portability.

Interestingly, eclipse is also the STEM project's Java development environment. If this seems a bit strange at first, don't worry, as you understand more about eclipse and the project this will make more sense. The project is organized and managed as an open source project. Much of the inspiration, philosophy and techniques for its management are taken directly from the book producing open source software by Karl Fogel (see the references later in this document).

Step-by-step for OHF STEM developers

  1. Read this article.
  2. When you find missing, confusing, erroneous information please contribute, by fixing the problem. This Wiki allows any registered user to update content. Please do!
  3. Visit the OHF project page. Bookmark it.
  4. Subscribe to the project mailing list.
  5. Install Java 5.0 and Eclipse 3.2] [?]
  6. Obtain the source code for the STEM project from the CVS repository. [?]

STEM Installation Instructions

Installing Java™ 5 JVM

STEM requires Java Version 1.5. IBMers should obtain the IBM version of Java 1.5. Others can use either IBM's Java 1.5 or the Sun Java 1.5 [[1]].

For the IBM Java:

  • Register with JIM, IBM's “Java™ Information Manager”
When you register you need to specify why you need access to Java™.
  • When you receive authorization in the form of an email download the file (e.g., ibm-java2-sdk-50-win-i386)
  • Run the installation program by double clicking on the file.

Installing the Eclipse Environment

Goto STEM Eclipse Setup

Running Stem as a standalone application

If you want to first tryout STEM as an application then we provide a standalone version of STEM that only requires that you have Java 1.5 or higher installed.

You can get the file by going to the project page: http://w3.opensource.ibm.com/projects/stem/ and then clicking on "Files". Download stem0.1.0.zip (it is a very large file) and unzip it to your favorite directory.

This is a self-contained stand-alone version of STEM that is launched by double-clicking on the "STEM.exe" executable file in the root directory of the expanded archive. You'll need to have Java1.5 installed for it to run, but if you do and it's on the path, you should be greeted by the STEM "splash screen" while it starts up.

  • Go to Windows->Preferences->STEM->Simulation Management and enable "Pause simulation after each cycle" and set the seconds to pause to 2.
  • Open the Simulation perspective.
  • Open the Map view with Window->Map to see the spread of the disease.
  • Select the Spanish Flu Scenario under STEM Internal Data Test in the Scenario's view
  • Select Stem->Run from the menubar or toolbar.

The Scenario only has the USA and Mexico at this time.

To run the Stem-GoogleEarth view:

  • You must have installed GoogleEarth V4
  • Select the GoogleEarth View. Window->Other->Stem->GoogleEarth View
  • Select Window-Preferences->Stem->GoogleEarth and set:
    • Check Method -> Direct Launch
    • Check "Automatically process every simulation"
  • Select the Spanish Flu Scenario under STEM Internal Data Test in the Scenario's view
  • Select Stem->Run from the menubar or toolbar.

Software Engineering

Coding Conventions and Guidelines

As with any product being built by a team, there are various areas where standards, conventions, and other guidelines can play a role in helping to ensure that the resulting product presents to developers and customers as a unified whole rather than as a loose collection of parts worked on by a variety of individuals each with their own styles and ways of working.

The STEM project will use the conventions and guidelines used by the Eclipse project. See the Eclipse Development Conventions and Guidelines.

The most important guidelines for STEM code are that it have good JavaDoc documentation and not generate compiler warnings.

The Eclipse compiler verifies the code against a preference list and will generate warning messages for code that does not follow rules specified in the compiler preferences. For example, it will check for "unchecked Generic type operations" and give a warning. We ask you removes all of the Eclipse compiler warnings before submitting the code. Also preferences for the following JavaDoc options should be changed to generate warnings and the warnings removed by fixing the code and/or creating accurate and informative Javadoc comments,

 window->preferences->java->compiler->javadoc:
    Process Javadoc comments
      Malformed Javadoc Comments:         warning
      Missing Javadoc tags(public)        warning
      Missing Javadoc comments(Public)    warning

If you are the owner or creater of a STEM subproject you can create more restrictive standards by checking in a set of project preferences. However, please do not remove warnings by checking in project preferences that ignore bad coding practices.


Copyright Statement

Each source file should include the following copyright statement. It should follow the package statement and proceed the import statements.


package org.eclipse.ohf.stem;
/*******************************************************************************
* Copyright (c) 2006 IBM Corporation and others.
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Eclipse Public License v1.0
* which accompanies this distribution, and is available at
* http://www.eclipse.org/legal/epl-v10.html
*
* Contributors:
*     IBM Corporation - initial API and implementation
*******************************************************************************/ 
import ... ;


National Language Support

STEM supports languages other than English. The basic process is to provide properly named properties files that mirror the "native" English properties files. These files are grouped into a "plug-in fragment" which acts as an "add on" to a plug-in and adds the files of the fragment to the plug-in as if they were there originally. We separate them so that additional languages can be added without changing the original plug-in.

If a native file is named "messages.properties", then the corresponding file with Spanish translations for the messages would be named "messages_es.properties". It is also possible to provide translations that are specific to a particular country, for instance, for Canadian English, the corresponding file would be "messages_en_CA.properties". For Californian English it would be "messages_en_US_CA.properties". This follows the regular Java conventions.

To get us started, I've created one new plug-in fragment called "org.eclipse.ohf.stem.ui.nl1" which contains the properties files for the main UI component of STEM in the plug-in "org.ecliopse.ohf.stem.ui". Each of the other plug-ins with translatable strings will require their own (yet to be created) plug-in fragment. I also created properly named, untranslated, properties files for Californian English, Canadian English, Spanish, Hebrew, Tamil and Chinese in the new fragment.

To start STEM (Eclipse) in a language different from the working language of the operating system, you need to use the "-nl" command line parameter. For example, use "-nl en_US_CA" to start STEM in Californian English, or "-nl es" to start it in Spanish. You might find it useful to create a new launch configuration in Eclipse with the parameter specified. I have one for each language.

1) Use the "Run..." menu item to open the "Create, manage, and run configurations" dialogue. 2) Duplicate the Eclipse application you use to launch STEM and rename the new one to reflect the language (e.g., "STEM Californian") 3) Select the "Arguments" tab 4) In the "Program arguments" text box enter the command line parameter (E.g., "-nl en_US_CA" without the quotes, for Californian English). 5) Apply 6) Run

Open the Active Simulations View and you should see a different title than normal.


Here are some good resources for more detailed information:

http://www.eclipse.org/articles/Article-Internationalization/how2I18n.html

http://www.eclipse.org/tptp/home/documents/process/development/translation_rules_of_thumb.html

"Building Commercial Quality Plug-ins", Clayberg,

"The Java Developer's Guide to ECLIPSE", D'Anjou, et al.

Source Code Control

<P>All of the files that constitute the STEM project are maintained in a “source code control” system. Anyone can obtain a copy of the files in the system, but only people designated as “contributors” are allowed to add new files or make other changes to the repository.

The only files that are in the repository are those that cannot be

derived from others. For instance, Java source files would be in the repository, but not Java class files.

Plans to move STEM to Open Source repository

Soon the STEM repository will be moved to the official Eclipse CVS repository and the following Subversion information will no longer apply.

Anyone will be able to checkout the STEM source code and data from the CVS repository as described later.

To submit to the Eclipse CVS repository you will need a Bugzilla account and be added to the list of committers.

Subversion Source Code Control System

The project uses the Subversion source code control system. This is an open source revision control system that is designed to be the successor to CVS. Subversion was conceived and implemented by developers who are intimately familiar with CVS and so was designed to be a superior replacement. It includes a number of features missing from CVS including atomic operations, full version support for folders and better performance (this is an incomplete list). Most new open source projects are selecting Subversion to manage their source code repositories.

While Subversion performs a similar function as CVS, it differs from the later in a very fundamental way. In CVS, each file has a version or revision number which changes as it is changed and checked-in to the repository. In Subversion, there is only one global revision number for the entire repository and each time any change (a “commit”) is made to the repository, this number is increment. Subversion is, in essence, a “versioning file system”. The concept is simple, any state of the file system since it came into existence can be recreated, all one needs is the “revision number”of the desired state and it can be “checked out” from the system. For instance, the state of the file system after the three hundred and thirty fourth change is represented by the revision number “r334” (the prefix “r” is required). Understanding this, it should be clear that from one revision to another, a file can be exactly the same even though “its” revision number is different. The key point to remember is that the revision number is not for the file, but for the repository.

For example, a newly created repository is at revision “r0”. If we add file “foo.java” and commit it to the repository, the revision number of the repository would become “r1”. If we add another file “bar.java” and commit it, the revision number of the repository will increase to “r2”.

Subversion also differs from CVS and other repository systems in the way it handles “branches” and “tags” of the repository. A branch is an alternative version of the repository usually used to do parallel development without affecting the main development path. A tag is basically a label attached to a version of the repository used to name some significant state such as a release. In CVS these concepts are specifically implemented and maintained by the system, in Subversion these concepts have no specific support. Instead they are implemented by creating new “sub-folders” in the repository and then copying the appropriate file system tree in the repository to the new sub-folder. On the surface this seems very strange and inefficient. The trick is that Subversion is implemented in such a way that copies are very fast and very efficient. When a file is copied in the repository nothing much changes except for a few bookkeeping entries.

By convention, but not enforced by the system, the root of a Subversion source code repository contains three top-level folders named “trunk”, “branches” and “tags”. The trunk folder holds the main copy of the code being developed. The branches folder contains sub-folders that define different branch copies of the contents of trunk. The tags folder contains sub-folders that each define different “tagged” copies of the contents of trunk. The names of the folders in both the branches and tags folders act as the labels of the corresponding “branch” and “tag”. Development occurs (i.e., files are committed) under trunk and branches, but not tags. The development efforts on the branches sub-folders should have a life-cycle that causes their contents to be merged back into the trunk (how to do that is another story) or abandoned, and then ultimately, regardless of their fate, deleted from the current revision of the repository. The tags folder should never be changed. It represents a labeled snapshot of the trunk.

<diagram of trunk/branches/tags here>

Getting Access to the STEM Source Code Repository

There are three ways to access the STEM source code repository, through the Subclipse eclipse plug-in, through the tortoiseSVN integrated windows shell tool, and through the command line using Subversion commands. Installation of Subclipse was described earlier in this document and we give specific instructions on how to use subclipse but you are free to use TortoiseSVN or the command line if you prefer.

Accessing the STEM Source Code Repository with Subclipse

These instructions assume that the Subclipse plug-in has been installed in eclipse.

  • Select Window->Open Perspective->Other->SVN Repository Exploring
  • In the “SVN Repository” perspective right click on the view to bring up the context menu and select “New→Repository Location”
  • In the dialog there will be a box labeled “Url:”, enter https://svn.opensource.ibm.com/svn/stem/trunk This is the URL of the source code repositories “trunk”.
  • In the “SVN Repository” view you will now have a list of all of the current projects. Select the ones you want (usually all) and from the "right click" select “Check Out...” This will get all of the projects into your eclipse workspace.

Accessing the STEM Source Code Repository with tortoiseSVN

TortoiseSVN is a Subversion client, implemented as a windows shell extension. One would download and install TortoiseSVN from the Tigis.org [[2]] web site.

Accessing the STEM Source Code Repository with CVS

For use when STEM is on Eclipse.OHF

At the current time, both users and developers of STEM must access the code and data from the CVS repository in order to use the system. However all elements of the Eclipse STEM project is available for anonymous read-only access to the development CVS repository. Using anonymous access you can checkout the code and data to your local system. You can then use the system and if you wish modify it locally. However you can not use anonymous access to write it back to the repository. This is handy if you would like to fix a bug or add a feature. Get the code via anonymous access, do your work and then pass the work on to a committer (in a patch attached to a bug report) for inclusion in the repository. Committers love to have bugs fixed for them!

To use anonymous access from a running Eclipse platform, simply go to a Repository View and add a new CVS repository location. Use the following information to connect:

Anonymous CVS Connection Information
Host dev.eclipse.org
Repository Paths /cvsroot/technology
User anonymous
Password leave blank
Connection Type pserver

Expand the list from:

 HEAD -> org.eclipse.ohf -> stem
  • org.eclipse.ohf.stem.common
  • org.eclipse.ohf.stem.core
  • org.eclipse.ohf.stem. ...
  • org.eclipse.ohf.stem.utility

Select all of the stem projects and checkout the projects to your Eclipse workspace (e.g. c:/stem)

The repository is also available for browsing here.


  • Committer access to CVS

Developers with commit rights have individual user ids and passwords in the Eclipse project development repository. As a committer you can use SSH (Secure SHell) to connect to the CVS repository as follows. Go to a Repository View and add a new CVS repository location. When asked for the repository location enter the following:

Committer CVS Connection Information
Host dev.eclipse.org
Repository Paths /cvsroot/technology
User (your committer user id, supplied by the webmaster)
Password (your committer password)
Connection Type extssh

Once your information is authenticated, you can browse the repository and add projects to your workspace. If you do some changes that you'd like to contribute, after testing and ensuring that you have followed the contribution guidelines, you are free to release your changes to the repository. Of course, you can only release changes to projects for which you have commit rights. The current list of committers for OHF can be found here.

Note that you can use the SSH protocol and your Eclipse user id to access projects for which you are not a committer but you will not be able to release changes.

More information about CVS usage with Eclipse is available here.

Creating a project in the STEM Source Code Repository with Subclipse

When you create a new Eclipse project you are going to want to be able to save it in the source code repository both so it can be backed up and so that you can share it with others. Basically you will create the project using eclipse and then initially store it as a "branch" in the Source Code Repository. You can invite others to access your branch when you get ready to have others try it. At some future point, it may be decided that this project should be migrated to the Source Code Trunk.

The process is as follows:

  • Create the Eclipse project using the Eclipse wizards.
  • "Right click" on the project name and select Tean->Share Project
  • On the "Share Project with SVN" screen, select "create new repository location"
  • On the "Enter Repository Location ..." screen in the "URL" field enter "https://svn.opensource.ibm.com/svn/stem/branches" and click "Next"
  • On the "enter FolderName" screen, select "Use project name as folder name" and click "Finish"

If it complains about the name, that may be because someone has already created a project with that same name and you need to choose a different name. Question? Should there be a project name registry?

If you want to share your project with others, give them the name of the project and tell them to access the project using the Subclipse command to access it. For example, if you created a project "com.ibm.almaden.stem.dogflu" then they would do the following:

Preparing the STEM environment

Preparing the STEM scenario

The first step is to run a utility that will build a scenario that you will later use to run the STEM application.

  • Select Run -> Run -> Run a Java Application
    • On the Main screen:
      • Specify Name: Main
      • Specify Project: org.eclipse.ohf.stem.internal.data
      • Specify Main Class: org.eclipse.ohf.stem.internal.data.Main
    • On the Arguments screen
      • Specify -Xmx512m in the VM Arguments box
    • Select Run

Preparing the GoogleEarth Servlets

If you plan to run the GoogleEarth demo interface, you will need to setup the Servlet environment that is required.

  • Open a command prompt terminal window.
  • cd yourStemworkspace
  • cd org.eclipse.ohf.stem.ui.ge
  • ant

Running/debugging the STEM application

It is possible to run STEM as an application from the Eclipse Development environment without actually creating the standalone Stem application. Earlier sections described how to set up the environment and checkout the STEM source files. Once you have done that you will want to run the application using the compiled source. A later section will describe how to build the standalone Stem application.

This section will describe how to run and test the STEM application from the source projects. It assumes that you have downloaded the following projects from CVS/SVN and the build was error free.

  • STEM projects
    • org.eclipse.ohf.stem.core
    • list the rest

Go to the Eclipse Launch window by selecting "Run" or "Debug" from the "Run" option.

  • Select Run -> Run
    • On the Main screen:
      • Specify Name: STEM2
      • Select Run Eclipse Application
    • On the Arguments screen
      • Specify -Xmx512m in the VM Arguments box
    • Select Run

The system will grind away and start a new instance of the Eclipse. If you have not done this before, you should be aware that this new instance is being controlled by your primary eclipse instance and console output from your application will be sent back to your primary Eclipse. Also you can use the debugger and the debugging controls for the application will be on the primary eclipse window as the application runs in the secondary Eclipse.

The Eclipse application at this point shows the Eclipse Welcome screen so we next need to setup the STEM environment.

  1. Select windows->Open Perspective->Other->STEM
    You now have the STEM main screen with numerous windows that will be described separately. insert an image here
    1. STEM Project Explorer
    2. Active
    3. Progress
    4. Scenarios
      The Scenarios window is use to select a prebuilt scenario for a simulation. By selecting leafs in the tree you can discover an existing scenario for running a simulation. Select the scenario of choice and click the Run or Advance icon on the toolbar.
    5. Models
    6. Graphs
    7. Observers
    8. Sequencers
    9. Decorators
    10. Properties
    11. Tasks
    12. ErrorLog
      This log will contain information about any errors that occur while running the application. If things don't work as you expect, check this view to see if there are any errors or exceptions that have occured. Note that the ErrorLog on the secondary Eclipse will show errors and exceptions that occur in the application being tested but stdout/stderr will be sent to the Console of the Primary Eclipse. Also if an exception is caught by the application and not passed to the built in log facility it will only show up on the Primary console. Likewise, if an exception is not caught and sent to stdout/stderr then it will only show up on the secondary ErrorLog. Confusing!


There are also secondary application that need to be selected from the Views window.

  1. Select windows->Open Views->Other->STEM
    You now have a list of optional applications some of which will be described below.
    1. GoogleEarth
      This is an interface between STEM and the GoogleEarth application. The basic idea of the support is to allow The information about the geographic spread of diseases to be reflected on the GoogleEarth Web map. An example follows. insert an image here

Creating or testing a new standalone STEM application

At some point you may want to create a new version of the standalone Stem application. Or more likely, you may need to verify that changes you have made will work in the standalone version. Or perhaps create a version of STEM for a new platform. To create a new temporary version of the STEM application for testing do the following.

  • Select the org.eclipse.ohf.stem.ui project
  • Select stem.product
  • From the launcher tab
    • specify Program arguments "-consoleLog"
    • specify VM arguments "-Xmx700M"
  • From the Overview tab
    • select Launch or Launch in Debug mode.

It should start a new image of STEM and launch it.

Software Engineering Documentation To Do's

Describe the basic development philosophy of the project and the basic ideas behind “agile” software development.

Explain how to build the system

Explain how to test the system

Explain how to submit a bug report

Explain how to use JUnit



STEM subprojects

STEM consist of a basic core system and (in the future) many projects that either use the basic system or enhance it. The following section describe the subprojects that use STEM or enhance it.

STEM - GoogleEarth Interface.

STEM is a computer software system for defining and visualizing simulations of the geographical spread of contagious diseases. One way to visualize this geographical information is to overlay it on the GoogleEarth 3D world model.

The STEM-GoogleEarth project (STEM-GE) enables the logging of the spatial data with disease statistics included as it runs. Either simultaneously or after the fact, the logged data(in the form of KML files) is read by GoogleEarth and displayed by mapping disease state to color intensity.

To run the STEM-GoogleEarth Interface you need to do the following:

  • Build the ge project
    • Checkout the org.eclipse.ohf.stem.ui.ge project into Eclipse. (See earlier instructions)
    • cd to the above ge project directory.
    • ant war
  • Start STEM application
  • Display the STEM-GE Window
    • windows->open views->Other->Stem->GoogleEarth

There are numerous ways that you can use GoogleEarth with your simulations. We will not describe them all. The STEM-GE Preference Page is described below. That is where you specify many options that control what the STEM-GE interface does. The most common use of STEM-GE is to run a simulation and have it write KML files to a folder. Simultaneously GoogleEarth is reading these KML files via a webServer and displaying the results of the simulation on the GoogleEarth screen.

For example, if you have a predefined scenario that you want to run, then do the following:

   To be completed


STEM-GoogleEarth Preferences

The STEM-GoogleEarth interface has a set of preference that control how the application works. This preference page is accessed by going to windows->preferences and selecting the GoogleEarth entry.

You will get the following window: File:GEPreferences.jpg

  • Preferences
    • Choose the Method used to display STEM Results
      • LogOnly
        With this option, the KML files are written but not displayed by GoogleEarth.
      • Log+Servlet
        With this option, the KML files are written and then displayed by GoogleEarth. GoogleEarth actually requests the file from a webserver Servlet whcih actually reads the file.
      • AsysncServlet
        The KML is written on every cycle, overlaying the previous cycle. GoogleEarth asks for new data on a predetermined interval and is sent the current KML.
      • AutoLaunch
        With this option, the KML files are directly sent to GoogleEarth. This can cause problems because GoogleEarth may get files sent at inopportune times but it is more efficient.
      • Manual Launch
        The map is generated by user selection of MapDisplay from the context menu (Right Click).
    • Folder for KML Logging
      This is the folder where STEM will write the KML files that GoogleEarth will read. If it already contains KML files, the user will be given the oportunity to delete them, keep them or choose a new folder.
    • Hostname:port for external webserver:
      This is the required hostname and port for an external webserver. Normally the internal webserver would be used so this is not needed but there are cases where one might want to use an existing web server.
    • Use internal webserver
      This is used to cause the webserver built into Eclipse to be used.
    • Automatically startup GoogleEarth
      If specified then when the STEM-GoogleEarth view is started, then the GoogleEarth application is also launched.
    • Automatically log KML for every simulation
      if specifid, then when you start any simulation running, it will automatically log files to GoogleEarth. Only the first one will be displayed by GE since it would be counterproductive to show 2 different views at the same time.
    • Only write a KML file file every Nth cycle
      If the simulation does not change rapidly from cycle to cycle, significant overhead can be saved by only sending data to GoogleEarth every Nth cycle.
    • Chose the STEM Aspect to be displayed
      • Susceptible/Exposed/infectious/Recovered
      • Any/All
        The graphical display can only display one of the disease attributes at a time. Normally you would select one of S E I or R but Any would be specified when you are displaying an existing folder and you want whatever was logged to be displayed. All would be specified when you want all of the disease statistics to be logged. (4 files for each cycle).
    • Allow debug output on Console
      This is used for problem determination.

STEM Data

In Process documentation This section is in the very early stages of documentation. Please help complete it.


An important component of STEM is the large collection of data that it contains. This section will attempt to describe the different data that is available, where it is and how it is used.

Definitions

Administration Level The administration level for geographic data refers to the "political resolution" of the data sets. The United Nations defines political divisions called "Administration Levels".

The highest level is "UN Administration Level 0" which corresponds to "countries". We have 244 such "countries", we get our definition of a country from the ISO-3166-1 codes, of which there are 244. There is a ISO-3166-1 code for the United States (a country), and one for Puerto Rico (not a country, but a slightly separate political division). For the United States the ISO-3166-1 2 character code is US and the ISO-3166-1 3 character code is USA.

The next level down is "UN Administration Level 1", which for the United States are the states and for Canada are the provinces and territories. Below that is "UN Administration Level 2" The definition of these areas varies from country to country which is why we use the "level" instead. Level 2 is the limit on our current data sets. In the future we could add higher resolutions. For instance, for a small country like Israel we might go to level 3 and use something like a census track as the location.


Latitude: Latitude gives the location of a place on Earth north or south of the Equator. Latitude is an angular measurement in degrees (marked with °) ranging from 0° at the Equator to 90° at the poles (90° N for the North Pole or 90° S for the South Pole). In Stem, latitudes north of the Equator are positive values and south of the equator are negative.

Longitude: Longitude describes the location of a place on Earth east or west of a north-south line called the Prime Meridian. Longitude is given as an angular measurement ranging from 0° at the Prime Meridian to +180° eastward and −180° westward. The Greenwich meridian is the universal prime meridian or zero point of longitude.

ISO3166 code ISO 3166 is a three-part geographic coding standard for coding the names of countries and dependent areas, and the principal subdivisions thereof. The official name is Codes for the representation of names of countries and their subdivisions.

  • ISO 3166-1 codes for country and dependent area names.
    • ISO 3166-1 alpha-2 two-letter country codes
    • ISO 3166-1 alpha-3 three-letter country codes
    • ISO 3166-1 numeric three-digit country codes
    • ISO 3166-2 Codes for the representation of names of countries and their subdivisions -- Part 2: Country subdivision code - defines codes for the principal subdivisions of a country or dependent area.

A list of all the county (Administration 0) codes is here: http://www.davros.org/misc/iso3166.html

Data Location and Usage

STEM Projects that contain data The following STEM projects contain data files that are used in STEM. In most cases these projects also contains code that processes the data.

  • Eclipse Project names
    • org.eclipse.ohf.stem.geography
      Contains the Latitude/Longitude data for the Administration areas.
    • org.eclipse.ohf.stem.internal.data
      Contains the properties files that describe all of the data in STEM.
    • org.eclipse.ohf.stem.data
      No longer actively used and should be ignored.
    • com.ibm.almaden.stem.utility
      Code and data used to prepare the properties files

Property files in org.eclipse.ohf.stem.internal.data The following property files are found in the following directory. NNN is the 3 character Country code and N is the administration level.

  • resource/data/country/XXX/ There is a separate subdirectory for each country.
    • XXX_N_area.properties This property file contains the area of the administration level in square kilometers. The Key is the key for the administration level ( level 0 = USA; Level 1 = US-CA; Level 2 = US-CA-06075
    • XXX_N_human_2006_population.properties This property file contains the population of the administration level.
    • XXX_N_node.properties This property file contains the full name of the administration area. >> we need an example of how to access it <<
    • XXX_names.properties This property file contains a xref of both Level 1 and level 2 names.
  • resource/data/relationship This contains the following subdirectories.
    • airtransport
    • commonborder See below.
    • airtransport
    • airtransport


  • resource/data/decorator/disease This contains property files that describe existing diseases.


Spacial Data (Geographic Coordinates) that provides the latitude and longitude coordinates for the borders of the Administration areas.

  
 Project: org.eclipse.ohf.stem.geography
 Path:   resource/data/geo/country/XXX/
      XXX_0_MAP.xml
      XXX_1_MAP.xml
      XXX_2_MAP.xml
 
 Example URI: platform:/plugin/org.eclipse.ohf.stem.geography/
                    resources/data/geo/country/USA/USA_2_MAP.xml


 Key Format: 
   For level 1 data, the key is the ISO3166-2 code. 
     An ISO3166-2 code is composed as follows: 
       Two letter country code followed by up to three 
       alphanumeric characters for the level 1 administration.
   For level 2 data, the key is the ISO3166-2 code followed by
   up to six digits. 
     The leftmost two digits indicate the level 1 container of a 
     level 2 administration (i.e. California is a level 1
     container for Orange County; a level 2 administration).  
     The two digits were taken from a lexicographic sorting of 
     all the level 1 administrations within a country. 
     Similarly, the four leftmost digits indicate the level 2
     administration. 
     Again, these four digits are an index into the lexicographic
     sorting of all level 2 administrations within a level 1
     administration.


Common Border Data that describes which Administration areas have common borders.

  
 Project: org.eclipse.ohf.stem.internal.data
 Path:   resource/data/relationship/commonborder/
      XXX_2_XXX_2.properties  
                Common Borders between admin areas within country XXX 
      XXX_2_YYY_2.properties  
                Common Borders between admin areas of country XXX to 
                the admin areas of Country YYY where XXX and YYY have 
                a common border.
      The property files will list the bordering admin level 2 areas. 

 Example URI: platform:/plugin/org.eclipse.ohf.stem.internal.data/
                resources/data/relationship/
                commonborder/AFG_2_CHN_2.properties
 Generated by:  NeighborUtility.java      
 Located in:    org.eclipse.ohf.stem.internal.data

Tools

Tool

Version

URL

OpenOffice

V2.0.1

http://www.openoffice.org

IBM's Java 5 JDK

5

http://w3.hursley.ibm.com/java/jim

Subversion

V1.30

http://subversion.tigris.org/

TortoiseSVN

V1.4

http://tortoisesvn.tigris.org/

Eclipse IDE

V3.2.1

http://www.eclipse.org/downloads/

cruisecontrol

V2.3.1

[http://cruisecontrol.sourceforge.net/index.html
http://cruisecontrol.sourceforge.net/index.html]

Jdraw

V1.1,4

[http://www.j-domain.de/homepage.php?page=20

Eclipse Features and Plug-ins

Plug-in Description URL
Subclipse Subversion client Subversion client
UMLet UML class diagram drawing tool http://homepage.mac.com/martin.auer/umlet
Metrics Java code metrics computations http://metrics.sourceforge.net
Merline Generator GEF generator from EMF http://sourceforge.net/projects/merlingenerator
EMF 2.2 Latest EMF downloads http://download.eclipse.org/tools/emf/scripts/downloads.php

Reference Sources

Books

Useful books is an article discussing books that have been useful in learning and developing for Eclipse.

Web Sites

Transition to Eclipse OHF project

During the next month (October 2006) we will be moving STEM to be a sub project of the Eclipse Open Healthcare Framework

  • Eclipse OHF website
The following link will take you to the OHF page on the eclipse.org website.
http://www.eclipse.org/ohf/

---

  • OHF WIKI
The following is the OHF top Wiki page.
http://wiki.eclipse.org/index.php/OHF

---

  • OHF Mailing List
Open Healthcare Framework Mailing list <ohf-dev@eclipse.org>
https://dev.eclipse.org/mailman/listinfo/ohf-dev
The archives for ohf-dev mailing list is at:
http://dev.eclipse.org/mhonarc/lists/ohf-dev/maillist.html

---

  • Newsgroup
The Newsgroup for OHF is:
news://news.eclipse.org/eclipse.technology.ohf
To access the newsgroup you will need to go to the following page and request a userid and password. (Note: you apparently have no choice in the selection of either the userid or the password)
http://www.eclipse.org/newsgroups/

---

  • Bug reporting
Eclipse uses the Bugzilla system for reporting and processing Bug reports for the OHF project.
The following page has a link for creation of a Bugzilla account.
https://bugs.eclipse.org/bugs/
The bug reporting page is:
https://bugs.eclipse.org/bugs/enter_bug.cgi?product=OHF
The following page can be used to find bugs in OHf.
https://bugs.eclipse.org/bugs/query.cgi
Enter OHF as the PRODUCT

Back to the top