ICISWiki/pedigree viewer for developers
From ICISWiki
Contents |
Note To Developers
Links
Parameters used for creating permanent links to pedigrees
The base URL is http://<hostname:port>/belisama/getpedigree.jsp.
| Parameter name | Parameter values | Notes |
|---|---|---|
| dsId | e.g. http://irislocal.org | A unique identifier of a data source where germplasm are going to be read from |
| germplasm | e.g. 155 | GID - an entry point to a pedigree |
| withMethods | on (or left empty) | label edges by method names |
| nhoodType | NONE, DER, MAN | type of pedigree (NONE=parental, DER=derivative neighborhood, MAN=maintenance neighborhood |
| rankDir | TB, BT, LR, RL | graph orientation |
| nodeFontSize | an integer | font size for nodes |
| edgeFontSize | an integer | font size for edge labels |
| wrapSize | an integer | maximum characters on a line in nodes; -1 disables text splitting |
| selectedGIDs | comma-separated list | list of GIDs whose nodes will be highlighted |
| selectedColor | e.g. #ffff00 | color code used to highlight nodes defined in parameter selectedGIDs |
| cacheDisabled | on (or left empty) | "on" disables usage of the cached pedigrees |
| wantedFields | @GID@, @GNAME@,... | comma-separated list of tokens specifying what fields should be put into the nodes - see the full list of token in the GermplasmNode API |
| derivativeColor | e.g. #ff9900 | color code for derivative methods |
| generativeColor | e.g. #00cc00 | color code for generative methods |
| maintenanceColor | e.g. #663300 | color code for maintenance methods |
| steps | an integer | number of parental generations to create |
| childrenSteps | an integer | number of children generations to create (only for neighborhood pedigrees) |
| stops | e.g. {"431748":0,"56":0} | where to stop when making partial pedigrees,in JSON format |
| clickAction | oldicis, newicis, ... | see the src/etc/config/project.properties.template -
but only few of them will work in the permanent links, outside of the web application |
For example, a complete URL for a pedigree may look like this:
Belisama run-time properties
The pedigrees in Belisama Toys can be influenced by a small number of run-time properties that are read from the project.properties file. The properties are mostly about the actions and URLs invoked when clicking in the graph.
| Property name | Property value | Default value |
|---|---|---|
| pedigree.node.url.pattern | URL used after clicking on a node; but pedigree.click.actions property has precedence |
http://iris.irri.org/action/gms?method=getGmsInfoTree&gmsId=@GID@ |
| pedigree.partial.edge.url.pattern | URL used after clicking on an ending edge in a regular (parental) pedigree | None |
| pedigree.partial.edge.parents.url.pattern | URL used after clicking on a parental ending node in a neighborhood pedigree | None |
| pedigree.partial.edge.children.url.pattern | URL used after clicking on a children ending node in a neighborhood pedigree | None |
| dot.path | a full path to the external dot program | None. The program must be on the PATH. |
| dot.verbose | boolean properties; report (into the log) information about the used dot program | false |
| pedigree.click.actions | List of internal identifiers that link to other properties -
all of them together defining what actions are displayed (and how they are displayed) in the popup window when a user clicks on a pedigree node. See method Config.getCombinedProperties for explanation how it works. <p/> Below this table is an example list of available actions - for the latest one, check the src/etc/config/project.properties.template. | None |
# --------------------------------------------------------------------
# Properties defining click actions in the pedigree
# (special click.actions ID is "separator_")
# --------------------------------------------------------------------
pedigree.click.actions = oldicis,newicis,details,separator_
pedigree.click.actions = subped,branchout,branchin,regular,separator_
pedigree.click.actions = select,unselect,highlight,unhighlight,separator_
pedigree.click.actions = dern,mann,separator_
details.label = Show germplasm details
details.url = javascript:getDetailsForGID('@GID@')
subped.label = Create a sub-pedigree
subped.url = javascript:getPedigreeForGID('@GID@')
subped.cssclass = disable-for-nhood
regular.label = Create a regular pedigree
regular.url = javascript:getRegularPedigreeForGID('@GID@')
regular.cssclass = disable-for-regular
subped.label = Create a sub-pedigree
subped.url = javascript:getPedigreeForGID('@GID@')
subped.cssclass = disable-for-nhood
newicis.label = Show germplasm in Zeus
newicis.target = _blank
#newicis.url = http://
oldicis.label = Show germplasm old page
oldicis.target = _blank
oldicis.url = http://iris.irri.org/action/gms?method=getGmsInfoTree&gmsId=@GID@"
select.label = Select for highlighting
select.url = javascript:selectGID('@GID@')
unselect.label = Remove from highlighting
unselect.url = javascript:unselectGID('@GID@')
highlight.label = Highlight now
highlight.url = javascript:highlightGID('@GID@')
unhighlight.label = Remove highlighting now
unhighlight.url = javascript:unhighlightGID('@GID@')
branchout.label = Remove parental branch
branchout.url = javascript:removeBranch('@GID@')
branchout.cssclass = disable-for-nhood
branchin.label = Restore parental branch
branchin.url = javascript:restoreBranch('@GID@')
branchin.cssclass = disable-for-nhood
mann.label = Show maintenance neighborhood
mann.url = javascript:getNhoodPedigreeForGID('@GID@'\,'MAN')
dern.label = Show derivative neighborhood
dern.url = javascript:getNhoodPedigreeForGID('@GID@'\,'DER')
Pedigree from the command-line
Once you have checked out the Belisama project and built it (by using ant) you can also create pedigrees from a command-line tool. For example:
build/run/run-pedigree -p -gid 155 -mc -o a.png
The command-line tool has a pretty much all possible options what pedigree to create. Start it with an -h parameter and you will see something like this:
Usage:
build/run/run-pedigree -l [general-options]
build/run/run-pedigree -lf[a] [general-options]
build/run/run-pedigree -p -gid <gid> [general-options] [pedigree-options]
build/run/run-pedigree -n der -gid <gid> [general-options] [pedigree-options]
build/run/run-pedigree -n man -gid <gid> [general-options] [pedigree-options]
build/run/run-pedigree -call -gid <gid> [general-options] [countries-options]
where basic options are;
-l ... list available data sources (of germplasm data)
-lf ... list available tokens representing germplams fields
that can be used in the node label and URL pattern
of a pedigree graph
-lfa ... list available tokens (as with -lf) but also all metadata
about all tokens
-p ... create a pedigree graph
-n der ... create a pedigree of the derivative neighborhood
-n man ... create a pedigree of the maintenance neighborhood
-call ... list all countries of the given germplasm
where <general-options> are:
-h[elp] ... print this help
-q ... "quiet" (less verbose mode)
-stack ... in case of any error it prints the stact trace
(without this option, it prints it only when a
serious runtime error occurs)
and where <gid> is a germplasm ID whose pedigree or countries
will be created.
Where <divedigree-options> are:
Data source - where to get germplasm data from:
-----------------------------------------------
-l ... list available data sources
-spi ... use SPI mechanism to discover all available data sources
-factory <class-name>
use given class name as a data source factory to provide
data sources
-ds <class-name>
use given class as a data source
-id <data-source-id>
use this particular data source (use '-l' to get a list of IDs)
[Usually, you use only one of the parameters -spi, factory, -ds
and-id. By default, the given GID (germplasm) will be looked in any
of them - using the first one found.]
Output of the pedigree graph:
-----------------------------
[-o <output-file>] [-<type>] [-withimap] [-withcmap]
where:
<output-file> is a file name where to create the graph
Default: create only a 'dot' format to the stdout
<type> is a typeof the create dgraph; can be one of these:
ps, svg, fig, png, jpg, gif, hpgl and dot
Default: taken from the extension of the given
<output-file>
-withimap ... additionally to <output-file>,
it creates a server-side map file
-withcmap ... additionally to <output-file>,
it creates a client-side map file
Number of nodes in the pedigree graph:
--------------------------------------
-full ... do not skip derivative and maintenance steps
(in regular, parental, pedigree)
-step[s] <number>
how many generation of parents to create
(default is all)
-cstep[s] <number>
how many generation of children to create
(for neighborhood pedigrees); default is
the same as -steps
-stop[s] <gid[=number][,gid[=number]...]>
create only partial pedigrees, stopping on the
specified GIDs, or 'number' steps (generations)
from the specified pedigree
Pedigree graph characteristics:
-------------------------------
-mt ... include germplasm method name as a text
-tb ... graph main direction is "top to bottom"
-bt ... graph main direction is "bottom to top"
-lr ... graph main direction is "left to right"
-rl ... graph main direction is "right to left"
Default: "top to bottom"
-nfontsize <font-size> ... font size for nodes in points
(default value is 10)
-efontsize <font-size> ... font size for edges in points
(default value is 7)
-wrapsize <integer> ... some parts of the nodes attributes
(names, locations,..) may be split into
several lines; this parameter defines
how long these lines should be
(default: no splitting)
-color[s] <gid=color[,gid=color...]>
what colors to use to highlight individual nodes;
gid identifies the node to be highlighted and the
color is either its name, or its numeric value
For example: -colors 155=red,11=#2020AA
-mcolor[s] <[DER=color],[GEN=color],[MAN=color]>
what colors to use to draw the edges, where
DER means edges representing derivative methods,
GEN means edges representing generative methods,
MAN means edages representing maintenance methods
-mc ... as -mcolors but using the default colors
Contents of the graph nodes:
----------------------------
-label <label-pattern>
where the <label-pattern> can contain tokens
that will be replaced by the germplasm data;
resulting labels are displayed in nodes;
for the list of tokens, use -lf
For example: -label '@GNAME@\n[@GID@]'
-tokens <token[,token]...>
here listed tokens will be used to create node labels;
it is another way how to specify the contents of nodes
(use -label, -tokens, or -all)
-all ... use all available tokens without a need to list
them by the -tokens parameter
-withlabels ... the labels (as defined by the -label, by
-token, by -all parameters, or default ones)
will be prefixed by their name (in all nodes)
And the rest:
-------------
-time ... print spent time
-nc ... do not use cache
[You can also start the whole script in a "profiler" mode by
putting ./profiler.sh in front of it - this works only on Linux.
For example:
./profiler.sh build/run/run-pedigree -p -nc -gid 155 -o a.png
]
How to install Pedigree viewer locally
Here is a brief introduction what you need if you wish to install Pedigree viewer locally, on your computer. There is no special supporting software for that in place - as it would be for an end-user application. On other hand, the whole Belisama Toys project uses the usual guidelines and best practices that makes it easier to install it. Still, it is not just a click-on-a-button setup.
Requirements
You have to install on your computer following software:
- Java JDK, standard edition (not only Java JRE), version 5 and above.
- Apache Ant, version 1.7.0 and above. You may also be able to use the Ant that is part of your Eclipse (if you are using one) - but having the standalone Ant installed is usually a good idea, anyway.
- Apache Tomcat, version 5 and above.
- Program dot for making graphs - it is part of the Graphviz package.
- An SVN client that will be able to check-out the BelisamaToys project from the subversion repository. It may be again the one which is part of your Eclipse - but I recommend to install (on Windows) the standalone SVN Tortoise.
- Finally, you will also need an access to an ICIS database. The database may sits on a remote computer, but such access will be much slower. I assume that the reason why the Pedigree viewer is being installed locally is because you wish to explore your ICIS installed database. The ICIS database must be loaded in the mySQL database engine.
Getting the code
In the text below, I am going to use command-line tools (ant for calling Apache Ant, svn for calling a command-line subversion client). Make your own adjustment if you have these tools within Eclipse or elsewhere.
Also, the examples of the command-lines are shown as used in the Linux operation system. For Windows, you may need to use slightly changed ones (for example, an argument that contains an equal character should be surrounded in double quotes - otherwise the Windows considers it as two arguments).
In order to check-out the BelisamaToys project:
svn checkout https://svn.cropforge.org/svn/pantheon/Belenus/projects/BelisamaToys
by using user name anonsvn and password anonsvn.
It creates a new folder BelisamaToys (unless you named it differently when using another tool for checking out). This folder is called (below and elsewhere in the documentation) a project folder. Everything (except configuring your Apache Tomcat server) is done within this folder.
Configuration
The configuration allows to customize the project according to your needs, to reflect the names of your local files, etc. You may configure a lot - but if you don't the most of the configuration properties have reasonable default values. Short story is that you will only definitely need to tell what is the user name and password to access your ICIS database, and where your Apache Tomcat server is installed on your computer.
The whole configuration is done by specifying properties which are simply pairs of a name and a value, separated by an equal character. The best place where to put such properties is in a file (or in several files). The text below tells what file names and what property names to use. But before going there, a few words on the time when the properties are being used.
There are two stages when the properties are being used: Some properties are used when you build the project - these properties are called built-time properties, other properties are used by the pedigree viewer itself when it is really used - those properties are called run-time properties. It looks like a clear distinction - but sometimes it is not that clear. The reason is that, in the time of building the project, some built-time properties are copied to new files, becoming the run-time properties. This is meant to simplify the process - but sometimes it may be confusing at the beginning. Now, back to the configuration.
First, make a copy of the file build.properties.template and name it build.properties. The file now has many properties, all of them commented out, which may help you to see what is configurable. As its name indicates, this file is mostly for the built-time properties (but some of them will be propagated to the run-time, as well). The only property that is mandatory here is the location of your Apache Tomcat server; the property contains a name of a directory where is your Tomcat installed. For example:
tomcat.home = /home/senger/Software/jakarta-catalina
The run-time properties are specified in the directory src/etc/config in two (or three) files whose names end with .template. You may edit directly these files. But the recommended best practice is to make a copy of these files, using whatever file name you wish and specifying these file names in the built-time properties in build.properties file. It sounds complicated, doesn't it? Here is explicitly what and how to do for the most important properties (the file names are examples, but why not to use them as suggested?):
Create a new file my.icis.properties. This file is your replacement of the src/etc/config/ICISLocalDataSource.properties.template template file. Put there the following properties:
icis.datasources = iris iris.dbname = iris.dbusername = iris.dbpassword = iris.dbhost = localhost iris.dbport = 3306 iris.name = IRIS-DS-laptop iris.id = http://laptop.irislocal.irri.org iris.whpedigree = true
The icis.datasources specify how many (and which) ICIS databases you want to access. There may be several crop-specific databases. The recognized values (at the moment) are iris, iwis and imis. These names constitute also prefixes to other properties for individual databases (such as iris.dbname for iris).
You definitely need to specify properties for the database name (dbname), database user name (dbusername) and database user password (dbpassword). Sometimes you need to specify the location of your mySQL database (dbhost and dbport). In the pedigree viewer, each database is represented as a data source that has its own name and identifier (specified by the properties name and id) - just make sure that you are using reasonably unique identifier, otherwise it does not matter.
Make sure that you keep there property whpedigree set to true. It significantly improves the pedigree creation time, especially for neighborhood pedigrees. But it is not enough to set it to true: you also need to create new tables (so called ware-house tables) in your ICIS database. It is not yet fully documented feature of ICIS. The fastest way is to download an sql script from the ICISDatabaseTools project and run in in your mySQL. For example:
mysql -uXXX -pYYY DBNAME -e 'source wh_create_children.sql'
Once you created and edited your own property file with the ICIS-related properties (in our example, the file is called my.ICISLocalDataSource.properties), you have to tell the system about this file. It is done by a build-time property (meaning: put this property in your build.properties file):
my.icis.properties = my.ICISLocalDataSource.properties
There is one more property file template, the src/etc/config/project.properties.template, which you can also customized. But because there is usually only one property that may need to be changed, the easiest way is to edit directly the template file. But you can also copy the template to your own file (e.g. my.properties), edit it, and announce its name in a property my.project.properties in your build.properties file:
my.project.properties = my.properties
The only important property there is the property dot.path that specifies where you installed the Graphviz dot program. Even this property is not needed, if your dot program is available from the PATH environment variable on your computer (note that this PATH must be available to your Tomcat server; if you just changed it, you may need to restart the server).
dot.path = a full path to the external 'dot' program
Building and deployment
The next step is to build it. This will take a while because it will first download all dependency libraries - and there is a lot of them. These libraries are stored in your computer outside the project directory (they can be shared by other Java projects but it is another story).
The place where they are stored depends on your operating system - usually it is in the folder .m2 (note the dot in the name) in your home directory. The folder is created and filled automatically. However, if you prefer to let it created elsewhere (for example, if you have disk space constraints in your home directory) you need to do an additional step: Create manually directory .m2 in your home directory and, inside this directory, create a file settings.xml where you specify a new location where you wish the dependency libraries to be stored:
<settings>
<localRepository>/your/better/place</localRepository>
</settings>
In any cases, in order to build everything type:
ant bootstrap ant
Having done this successfully, you can packed everything and copy it to your Tomcat server. This is called deployment:
ant deploy
After that you should be able to use, in your browser, the http://localhost:8080/belisama.
Additional configuration
If you are not accessing your Tomcat by using the http://localhost, you need to add two more properties to your build.properties file, the properties allowing to see the Google Maps of the germplasm locations:
# -------------------------------------------------------------------- # For setting the key for the google maps for a specific host-name. # The following hosts are always recognized (so you do not need to # get a key for them): # localhost # koios.generationcp.org # 202.123.56.214 # 192.168.1.5 # For other host name you need to get their key at # http://code.google.com/apis/maps/signup.html # and fill the below two properties # -------------------------------------------------------------------- gmaps.hostname = koios.generationcp.org gmaps.key = ABQIAAAAZhe5F7Vv-1Xq9DDyIlEQXxRAjmS4coJKHxO6wbjJwqxjOkGycxR2nRmPI7KkI77Jw9Afj_Z_T9AtRA
If you are changing any of your properties, you need to run again, at least:
ant config ant deploy
But to be on the safe side, I recommend the full re-built (it is fast now, because the dependency libraries are already downloaded on your computer):
ant clear ant deploy
