add geopy to environment and docs

docs/main.md

@@ -64,7 +64,33 @@ Curate metadata with a DB Browser (SQLite). Examples of modifying the BioSampleC
 
 ### Geocode
 
-TBD
+Geographic location for samples is coded at the level of country and
+province/state in the format "Country:Province". Optional sub-province level
+geocoding can be provided afterwards if desired "Country:Province:Foci".
+
+Place names should be compatible with Nominatim as implemented in GeoPy.
+
+```python
+from geopy.geocoders import Nominatim
+geolocator = Nominatim(user_agent="plague-phylogeography")
+place_name = "Armenia:Shirak Province"
+country_address = place_name.split(":")[0]
+province_address = ":".join(place_name.split(":")[0:2])
+
+# Geocode at country level
+location = geolocator.geocode(country_address, language="en",)
+print(location.address)
+> 'Armenia'
+print(location.latitude, location.longitude)
+> 40.7696272 44.6736646
+
+# Geocode at province level
+location = geolocator.geocode(province_address, language="en",)
+print(location.address)
+> 'Shirak Province, Armenia'
+print(location.latitude, location.longitude)
+> 40.918594 43.8403536
+```
 
 ## Genomic Alignment
 

workflow/envs/main/environment.yaml

@@ -28,6 +28,7 @@ dependencies:
   - bioconda:vt=0.57721
   # Phylogeny
   - iqtree=2.0.3
+  - conda-forge::geopy=2.0.0
   # Plotting
   - matplotlib=3.3.2
   - pandas=1.0.4

workflow/envs/merge/environment.yaml

@@ -41,6 +41,7 @@ dependencies:
 - biopython=1.76
 - blast=2.10.1
 - conda-forge::biopython=1.76
+- conda-forge::geopy=2.0.0
 - conda-forge::libiconv=1.15
 - conda-forge::markdown=3.2.2
 - conda-forge::nbconvert=5.6.0