GPS lookups.

administration.rst

@@ -99,6 +99,8 @@ Individual permissions can be set for each curator:
 * modify_site_users - allowed to modify site user details (you may not want to
   this! The user account can be used by multiple databases on the site and any
   changes to user details will be seen throughout the site).
+* modify_geopoints - allowed to modify the geography point GPS coordinate 
+  lookup table used for mapping.
 
 Permissions can be set by clicking the Update/delete button in the Permissions
 box in the admin functions area of the curator's interface: 

curator_guide/0210_populating_geographic_coordinate_lookup_values.rst

@@ -0,0 +1,32 @@
+.. _gp_lookups:
+
+.. index::
+   single: geographic coordinates
+
+**********************************************
+Populating geographic coordinate lookup values
+**********************************************
+If a field has the geographic_point_lookup attribute set to 'yes' in the
+:ref:`config.xml file<isolate_xml_field>`, field values can be mapped to GPS 
+coordinates to facilitate mapping.
+
+If the user has curator privileges with the 'modify_geopoints' permission set,
+or is an admin, a curator link to modify 'Geopoint field lookup' will be 
+available in the curator interface. This link is normally hidden but can be
+shown by selecting the 'Show all' toggle.
+
+To add a value, click the 'Add' link:
+
+.. image:: /images/curation/geopoint_lookup.png
+
+Select the 2 letter ISO country code and the linked field from the dropdown
+lists. Enter the town or city in the value field, and the GPS coordinates 
+in LATITUDE, LONGITUDE format.
+
+.. image:: /images/curation/geopoint_lookup2.png
+
+Now, whenever that specified field value is used, a map will appear in the
+isolate information page showing the location. In addition, these values will
+be used in mapping in the Field Breakdown and Microreact plugins.
+
+GPS coordinates can be mapped in bulk using the gp_town_lookups.pl script.

dbase_setup.rst

@@ -47,16 +47,17 @@ Create an isolate database the same way: ::
  psql -f isolatedb.sql bigsdb_test_isolates
 
 The standard fields in the isolate table are limited to essential fields
-required by the system.  To add new fields, you need to log in to the database
-and alter this table.  For example, to add fields for country and year, first
-log in to the newly created isolate database as the postgres user: ::
+required by the system as well as country and year. To add new fields, you 
+need to log in to the database and alter this table. For example, to add 
+fields for age and sex, first log in to the newly created isolate database 
+as the postgres user: ::
 
  psql bigsdb_test_isolates
 
 and alter the isolate table: ::
 
- ALTER TABLE isolates ADD country text;
- ALTER TABLE isolates ADD year int;
+ ALTER TABLE isolates ADD age int;
+ ALTER TABLE isolates ADD sex text;
  
 If you want to use the geography_point field type, used for storing and mapping
 GPS coordinates, then you will need to install the PostGIS module for 
@@ -72,8 +73,15 @@ below: ::
 [SRID 4326 represents spatial data using longitude and latitude coordinates on 
 the Earth's surface.] 
 
-Remember that any fields added to the table need to be described in the 
-config.xml file for this database.
+Fields can also be linked to a GPS lookup table and can then be mapped. If this
+is enabled then you need to ensure that PostGIS is installed and create 
+the lookup table by running the isolatedb_geocoding.sql script against the 
+isolate database with the following: ::
+ 
+ psql -f isolatedb_geocoding.sql bigsdb_test_isolates
+
+Remember that any fields added to the table need to be :ref:`described in the 
+config.xml file<isolate_xml_field>` for this database.
 
 The xml directory of the software archive contains example XML files for 
 sequence definition and isolate databases (rename these to config.xml). 
@@ -267,6 +275,11 @@ Any value set here can be overridden in a
     'yes'. If the all_plugins attribute is set to 'yes', the contig export 
     plugin can be disabled by setting this attribute to 'no'.
 
+* country_field
+
+  * Sets the field in which country is stored. Default: 'country'. This is 
+    needed for mapping.
+
 * curate_config
 
   * The database configuration that should be used for curation if different
@@ -831,6 +844,15 @@ Element content: Field name + optional list <optlist> of allowed values, e.g.::
     'no', default 'no'. This setting can be overridden by individual user
     preferences. 
 
+* geography_point_lookup
+
+  * Set to 'yes' if this field should be linked to a lookup table of GPS
+    coordinates in order to facilitate mapping within the isolate information
+    page and the Field Breakdown plugin. If any fields have this value set,
+    you need to install the lookup tables by running the 
+    isolatedb_geocoding.sql script against the isolate database. This also
+    requires that the PostgreSQL PostGIS module is installed.
+
 * group
 
   * Fields can be grouped in the isolate information page by specifying the 

dependencies.rst

@@ -65,4 +65,4 @@ Installing these packages will enable extra functionality, but they are not requ
 * MAFFT 6.8+ - sequence alignment used by some plugins.
 * Muscle - sequence alignment used by some plugins.
 * Splitstree4 - used by GenomeComparator plugin.
-
+* PostGIS - needed for geographical mapping.

offline_tools.rst

@@ -571,3 +571,64 @@ A full list of options can be found by typing: ::
  -s, --sender ID  
      Sender id number.        
      
+.. _gp_town_lookups:
+
+.. index::
+   pair: geographic point lookup values;populating
+
+*****************************************
+Populating geographic point lookup values
+*****************************************
+If a field has the geographic_point_lookup attribute set to 'yes' in the
+:ref:`config.xml file<isolate_xml_field>`, field values can be mapped to GPS 
+coordinates to facilitate mapping.
+
+These lookup values can be populated using the gp_town_lookups.pl script found
+in the scripts/maintenance directory. This script uses the Geonames dataset
+that contains GPS coordinates for towns and cities with populations of at least
+1000 people. The dataset is included in the datasets/Geonames directory.
+
+A full list of options can be found by typing: ::
+
+ gp_town_lookups.pl --help   
+ 
+ NAME
+     geography_point_lookups.pl - Populate geography_point_lookup table 
+     to set city/town GPS coordinates for mapping.
+ 
+ SYNOPSIS
+     geography_point_lookups.pl --database NAME --field FIELD --geodataset DIR
+    
+     Run this to populate any unassigned values in the geography_point_lookup
+     table.
+
+ OPTIONS
+
+ --database NAME
+     Database configuration name.
+    
+ --feature_code CODE
+     Geonames feature code. See http://www.geonames.org/export/codes.html.
+     Default is 'P' (towns/cities).
+    
+ --field FIELD
+     Name of field. This should have the geography_point_lookup attribute set to
+     'yes' in config.xml.
+    
+ --geodataset DIR
+     Directory containing the Geonames dataset.
+    
+ --help
+     This help page.
+    
+ --min_population POPULATION
+     Set the minimum population for town to assign. Note that all entries in the
+     Geonames database has population, so setting this attribute may result in 
+     some values not being assigned, but can ensure that only high-confidence 
+     values are used.
+    
+ --quiet
+     Only show error messages.
+    
+ --tmp_dir DIR
+     Location for temporary files. Defaults to /var/tmp/.