Running the Geocoder

Running the Geocoder

This guide provides step-by-step instructions for running the Exposome Geocoder to convert addresses or coordinates into FIPS codes.

---

Overview

The geocoder uses Docker containers to execute the DeGAUSS toolkit, which performs:

1. Address → Coordinates: Converts street addresses to latitude/longitude
2. Coordinates → FIPS: Converts coordinates to Census Tract (FIPS 11-digit) codes

---

Software Requirements

1. Docker Desktop (required)
2. WSL2 (Windows users only)
3. Terminal/Command Line access

Prerequisites

Before running the geocoder, ensure:

• Docker Desktop is running
• Input files are prepared (see Input Preparation)
• Working directory is set up

---

For CSV Input (Option 1 & 2)

Step 1: Verify Input Files

Ensure your input CSV file is in the input folder:

ls input_address/

Step 2: Run the Geocoder

Use the following Docker command to run the geocoder:

docker run -it --rm \
  -v "$(pwd)":/workspace \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -e HOST_PWD="$(pwd)" \
  -w /workspace \
  prismaplab/exposome-geocoder:1.0.3 \
  /app/code/Address_to_FIPS.py -i <input_folder_path>

Example:

If your input folder is input_address/:

docker run -it --rm \
  -v "$(pwd)":/workspace \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -e HOST_PWD="$(pwd)" \
  -w /workspace \
  prismaplab/exposome-geocoder:1.0.3 \
  /app/code/Address_to_FIPS.py -i input_address

---

For OMOP Input (Option 3)

Prerequisites

• OMOP CDM database with required tables
• Database credentials (username, password, server, port, database name)
• Network access to the database server

Command Format

docker run -it --rm \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v "$(pwd)":/workspace \
  -e HOST_PWD="$(pwd)" \
  -w /workspace \
  prismaplab/exposome-geocoder:1.0.3 \
  /app/code/OMOP_to_FIPS.py \
    --user <your_username> \
    --password <your_password> \
    --server <server_address> \
    --port <port_number> \
    --database <database_name>

Example

docker run -it --rm \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v "$(pwd)":/workspace \
  -e HOST_PWD="$(pwd)" \
  -w /workspace \
  prismaplab/exposome-geocoder:1.0.3 \
  /app/code/OMOP_to_FIPS.py \
    --user omop_user \
    --password SecurePass123 \
    --server db.example.com \
    --port 5432 \
    --database omop_cdm

---

Verifying Successful Completion

After the geocoder finishes, verify:

# Check output directory was created
ls -la output/

# List generated files
ls -la output/

You should see:

• Timestamped ZIP files with results
• LOCATION.csv and LOCATION_HISTORY.csv (if provided as input)
• Log files (if any errors occurred)

---

Next Steps

Once geocoding completes successfully:

1. Inspect outputs: See Understanding Outputs
2. Validate results: Check for geocoding quality and completeness
3. Proceed to linkage: If needed, continue to GIS Linkage

Return to Home