Usage

This section guides you through installing and running the GeoPopMap application. Follow these steps carefully to ensure a smooth setup. Each step is explained in detail so you can follow along without screenshots.

Installation Steps

  1. Download the Application

    You can either download the project as a ZIP file or clone it using Git.

    • As ZIP: Go to the GitHub repository page (https://github.com/your-username/GeoPopMap), click on the “Code” button, and select “Download ZIP”. Once downloaded, extract the contents to your desired location.

    • With Git: Open a terminal (or Command Prompt on Windows) and run:

      git clone https://github.com/your-username/GeoPopMap.git

      This will create a folder named GeoPopMap in your current directory containing all the project files.

  2. Install R Packages

    Open RStudio and set the working directory to the GeoPopMap folder (you can use the menu or the command setwd() in R). Then, run the following command in the R console to install the required R package:

    devtools::install(“code/GeoPopMap_app”)

    This command will install the GeoPopMap application and its dependencies. If you see any error messages, read them carefully; they often indicate missing system libraries or permissions issues. Make sure you have installed all prerequisites as described in the previous section.

  3. Load the Docker Image

    • Download the Docker image file from the GitHub repository:

      1. Go to the GitHub project page

      2. Navigate to “Actions” tab

      3. Find the latest successful workflow run named “build-docker”

      4. Click on the workflow run to open it

      5. Scroll down to “Artifacts” section and click “geopopmap-docker-image” to download

      6. Extract the downloaded file to get the Docker image file (e.g., geopopmap_docker_img.tar)

    • Place the downloaded Docker image file in the root of the GeoPopMap_app folder.

    • Open a terminal (or PowerShell/Command Prompt on Windows) and run:

      docker load -i geopopmap_docker_img.tar

    • Wait for the command to finish. You should see a message indicating the image has been loaded. If you get an error, make sure Docker Desktop (on Windows/macOS) or the Docker service (on Linux) is running, and that the file name matches exactly.

    Note for updates: If you already have a previous version of the GeoPopMap Docker image installed and want to install a new version, you need to remove the old image first:

    1. Check existing images: Run docker images -a to see all installed Docker images

    2. Identify the old GeoPopMap image: Look for the GeoPopMap image in the list

    3. Remove the old image: Use docker rmi IMAGE_ID where IMAGE_ID is the ID of the old GeoPopMap image

      1. Then proceed with loading the new image using docker load -i geopopmap_docker_img.tar

    Troubleshooting Docker permissions: If you get a “permission denied” error when running Docker commands, you need to add your user to the docker group:

    1. Add your user to the docker group: Run sudo usermod -aG docker $USER

    2. Log out and log back in (or restart your system) for the changes to take effect

    3. Verify the fix: Run docker –version to confirm Docker is accessible

      1. Alternative: You can also run Docker commands with sudo (e.g., sudo docker load -i geopopmap_docker_img.tar)

Running the Application

Once everything is installed, you can run the application from RStudio or the R console. In R, type:

GeoPopMap::run_docker_app()

This command will start the application inside the Docker container. After a few moments, you should see a message in the R console with a local web address (usually starting with http://127.0.0.1:xxxx). Open this address in your web browser to access the GeoPopMap interface.

Important: After the first successful launch, the Docker container will remain running. For subsequent uses, you can directly access the application at http://localhost:3838/ without needing to run the command again. The container will continue running until you stop it manually or restart your system.

If you encounter any issues, check the R console and terminal for error messages. Common problems include missing Docker images, Docker not running, or port conflicts.

Test Data

To help you get started with GeoPopMap, we provide a set of example datasets in the code/Data_test/ directory. These files contain realistic data that you can use to test all the application features.

Available Test Files

Population Data:

  • populations_test.csv - Population data with geographic coordinates (100 individuals)

  • populations_test_with_NA.csv - Same data with missing values for testing NA handling

Climatic Data:

  • climatic_test.csv - Climatic variables including temperature, precipitation, and bioclimatic indices (100 individuals)

  • climatic_test_with_NA.csv - Same data with missing values

Phenotypic Data:

  • phenotypic_test.csv - Phenotypic measurements (100 individuals)

  • phenotypic_test_with_NA.csv - Same data with missing values

Genotypic Data:

  • genotypic_test.csv - Genotypic markers with chromosome information (100 individuals)

  • genotypic_test_without_chrs.csv - Same data without chromosome information

Structure Data:

  • structure_test.csv - Population structure information (100 individuals)

Data Format

All test files are in CSV format and contain 100 individuals (IND_001 to IND_099) with the following structure:

  • Population data: Contains code, Longitude, and Latitude columns

  • Climatic data: Contains temperature (tmin1-3, tmax1-3), precipitation (prec1-3), bioclimatic indices (bio1), climate zones, and land cover

  • Phenotypic data: Contains various phenotypic measurements

  • Genotypic data: Contains marker data with individual codes and marker names

  • Structure data: Contains population structure assignments

Using Test Data

  1. Upload the test files in the “Data_input” tab of the application

  2. Use the files with “_with_NA” suffix to test the missing value handling features

  3. Try different combinations of datasets to test the merging functionality

  4. Explore all visualization features with these realistic datasets

The test data is designed to demonstrate all application features and provide a realistic example of the data types you might work with in your research.

Next Steps

Now that the application is running and you have access to test data, let’s proceed to the Data Management and Merging section to learn how to upload and manage your data.