After initializing the schema with the 'init' command, the first task you most likely will do with PersephoneShell is adding an organism. The concept of an organism is fundamental to the majority of the data in the Persephone system. The maps organized into map sets are assigned to a specific organism. The map sets and markers are associated with the organism by OrganismId. This means that you will need to create an organism entry before adding any map.

To do this use the add command (see Add). Each add command requires a target (in our case, organism) and a set of parameters. The properties of an organism are supplied in the form of a control INI file (see Control Files), which contains the data needed by PersephoneShell to add the organism record. The control file is referenced on the command line by using the argument '-c'. The following section shows the steps necessary to add Glycine max to the Persephone database.

In general, the format of the command is

add organism -c <controlfile.ini> [-t|-v]

Review a copy of the control file soybean.ini, which is included in the PersephoneShell's "Samples/Organism" folder and is shown below.


[Organism]
; Organism ID (optional, normally the same as TaxonomyId. If not specified, it will be auto-generated)
OrganismId=3847

; Look up taxonomy information in http://www.ncbi.nlm.nih.gov/taxonomy
; Taxonomy ID (optional)
TaxonomyId=3847

; Alternative ID: user defined ID
;AlternativeId=""

; Scientific name (required)
ScientificName="Glycine max"
; Common name (optional)
CommonName="soybean"

;PlantClassification: (optional). If plant, specify if the organism is monocot(0) or eudicot(1). 
PlantClassification=1

The optional field PlantClassification is reserved for future. You can safely comment this line out (put the semicolon at the beginning of the line) if the organism is not a plant or if you are not sure if it is a eudicot or a monocot. 

It is important to first test the command before the real execution. (Use the auto-complete feature to speed-up typing). Run the test using the switch '-t':

add organism -c Samples/Organism/soybean.ini -t

If the tests are successful, load the data into the database in the verbose mode ('-v'):

add organism -c Samples/Organism/soybean.ini -v

Advanced (you can skip it for now):

AlternativeId is used in case you want to have a hyperlink to a web page with an extra information about the organism. Currently, setting up this hyperlink requires manual database update, later this will be done by PersephoneShell during organism loading.

To enable the link in Persephone's form for Map Set properties, create a record in ORGANISM_CONFIG table. The URL to the external organism web page should have a placeholder %s which will be filled with the value of AlternativeId. For example, with pattern 'http://localdatabase?org=%s' and AlternativeId='a123', the generated hyperlink will be 'http://localdatabase?org=a123'

 The database record should have the following fields:

ORGANISM_CONFIG.APP_FEATURE='ORGANISM_LINK'
ORGANISM_CONFIG.CONFIG_KEY='ORGANISM_LINK'
ORGANISM_CONFIG.CONFIG_VALUE='http://somelink?id=%s'

The next step would be adding a map set for the newly-loaded organism.