Documentation

🚀 Getting Started

Welcome to the QGeoDash tool! This platform allows you to transform your CSV or Excel data into interactive, shareable geo-dashboards using a simple YAML configuration language. No coding experience required!

Quick Start

1. Create an account or log in to your existing account
2. Create a new dashboard from the admin panel
3. Upload your data (CSV or Excel format)
4. Configure your dashboard using YAML
5. Share your dashboard with a unique URL

🔐 Authentication

All dashboards are private by default. You need to be authenticated to create, edit, or delete dashboards.

Creating an Account

• Navigate to the login page
• Click on "Sign up here" to create a new account
• Provide a username, email, and password
• Once registered, you can log in with your credentials

📊 Dashboards

Creating a Dashboard

1. From the admin panel, click "New Dashboard"
2. Give your dashboard a meaningful name (at least 3 characters)
3. A unique dashboard ID and sharing URL will be generated

Managing Dashboards

• View: Click on any dashboard in the list to see its public view
• Edit: Click the pencil icon to open a modal and rename the dashboard
• Delete: Click the trash icon, confirm deletion in the modal
• Share: Each dashboard has a unique URL that you can share with anyone

📤 Data Upload

Supported Formats

• CSV (Comma-separated values) - Recommended
• Excel (.xlsx, .xls) - Automatically converted

Upload Process

1. Navigate to your dashboard's edit page
2. Click on "Add Data" button
3. Select one or more files (CSV or Excel)
4. Optionally, provide column type overrides in JSON format:

   {
       "date_column": "DATE",
       "value_column": "FLOAT",
       "category_column": "TEXT"
     }

5. The system will automatically create a database table and import your data

⚙️ YAML Configuration

The heart of your dashboard is the YAML configuration file. It defines the dashboard's name, layout, charts, map, and menus. YAML is a human-readable data format that's easy to learn.

Basic Structure

geo-dashboard:
    name: "My Dashboard Name"
    template: side_content
    download: false  # Set to true to enable data download button
    filters:
      - column: Year
        operator: ">="
        value: 2020
    stats:
      - type: bar
        title: "My Chart Title"
        x: category_column
        y: count
    interactiveFilters:
      - column: Year
        label: Year Range
        type: range
      - column: Country
        label: Country
        type: multiselect
    map:
      lat: latitude_column
      lon: longitude_column
    menus:
      about: "Information about this dashboard"
      stats: "Statistical summary"
      map: "Map description"

Available Templates

• side_content - Sidebar on the left, main content on the right (recommended)
• top_content - Menus on top, charts below
• content_side - Main content on the left, sidebar on the right
• content_bottom - Menus on top, charts in the middle, map at bottom

Data Download

Set download: true in the root of the config to display a "Download Data" button in the sidebar. When clicked, it exports the currently filtered dataset (respecting global and interactive filters) as a CSV file.

📈 Chart Types

Bar Chart

- type: bar
    title: "Sales by Category"
    x: category
    y: 
      column: sales
      aggregation: sum

Line Chart

- type: line
    title: "Trend Over Time"
    x: year
    y: 
      column: value
      aggregation: avg

Pie Chart

- type: pie
    title: "Distribution by Category"
    x: category
    y: count  # Simple count of rows

Stacked Bar Chart

- type: stackedbar
    title: "Species by Country"
    x: country
    y:
      column: count
      aggregation: sum
    stackBy: species

Aggregation Functions

• sum - Total sum of values
• avg - Average value
• count - Number of records
• min - Minimum value
• max - Maximum value
• count distinct - Number of unique values

🗺️ Map Configuration

Basic Map

map:
    lat: latitude_column
    lon: longitude_column

Styled Map with Clustering

map:
    lat: lat
    lon: lon
    clustering:
      enabled: true
      maxClusterRadius: 80
      disableClusteringAtZoom: 14
      limit: 15000
    style:
      colorBy: category_column
      sizeBy: value_column
      defaultColor: "#94a3b8"
      defaultSize: 6
      minSize: 4
      maxSize: 14
      rules:
        - field: category
          operator: "="
          value: "Type A"
          color: "#ef4444"
          label: "Category A"
        - field: category
          operator: "="
          value: "Type B"
          color: "#3b82f6"
          label: "Category B"
      legend:
        title: "Legend Title"
        position: "bottomright"

Reducing Map Payload with fields

By default, the map endpoints return every column of your table for every point. For wide tables (dozens of columns) this dominates both network transfer and browser rendering time, even with clustering enabled. Add a fields list under map to ship only the columns the popup actually needs.

map:
    lat: common_latitude
    lon: common_longitude
    fields:
      - source
      - countryCode
      - common_year
      - common_month
      - individualCount
    clustering:
      enabled: true
      limit: 3000
    style:
      sizeBy: individualCount
      rules:
        - field: common_year
          operator: ">="
          value: 2020
          color: "#00ff00"
          label: "2020–2026"

Clustering Options

• enabled - Enable/disable clustering (boolean)
• maxClusterRadius - Maximum radius of clusters in pixels
• disableClusteringAtZoom - Zoom level where clusters break apart
• spiderfyOnMaxZoom - Spread out clusters when zooming in
• chunkedLoading - Load markers in batches for performance
• limit - Maximum points to load per viewport

🔍 Filters

Filters can be applied globally to all charts and the map, or specifically to individual charts.

Filter Operators

• = - Equal to
• != - Not equal to
• > - Greater than
• >= - Greater than or equal to
• < - Less than
• <= - Less than or equal to
• like - Pattern matching (use % as wildcard)
• in - Value in a list
• between - Between two values

Global Filters

filters:
    - column: year
      operator: ">="
      value: 2020
    - column: country
      operator: in
      value: ["USA", "Canada", "Mexico"]

Chart-Specific Filters

- type: bar
    title: "Filtered Chart"
    x: category
    y: count
    filters:
      - column: status
        operator: "="
        value: "active"
      - column: value
        operator: ">"
        value: 100

🎛️ Interactive Filters

Interactive filters appear in the sidebar and allow users to dynamically filter the dashboard without editing YAML. They are defined in the YAML under interactiveFilters.

Types

• dropdown - Single-select dropdown
• multiselect - Multi-select dropdown with search
• range - Range slider for numeric columns

Example

interactiveFilters:
    - column: Year
      label: Year Range
      type: range
    - column: Country
      label: Country
      type: multiselect
    - column: Form
      label: Disease Form
      type: dropdown

💾 Data Download

If you set download: true in the YAML, a "Download Data" button appears in the sidebar. When clicked, it exports the currently filtered dataset (including all applied global and interactive filters) as a CSV file.

geo-dashboard:
    download: true
    # ... rest of config

The download respects all active filters, so users can export exactly the subset they're viewing.

👁️ Data Preview

On the dashboard edit page, a rich preview shows information about the uploaded data:

• Total number of records
• Table name
• Column names and their SQL types
• First 5 sample rows

This helps you understand the structure of your data before building charts and maps.

📋 Examples

Leishmaniasis Vector Dashboard

geo-dashboard:
    name: "Leishmaniasis Vector Surveillance Dashboard"
    template: side_content
    download: true
    filters:
      - column: Year
        operator: ">="
        value: 2000
    interactiveFilters:
      - column: Year
        label: Year Range
        type: range
      - column: Country
        label: Country
        type: multiselect
      - column: Form
        label: Disease Form
        type: dropdown
    stats:
      - type: pie
        title: "Top 10 VL Vectors by Abundance"
        x: species
        y:
          column: "Specie counts"
          aggregation: sum
        filters:
          - column: Form
            operator: "="
            value: VL
      - type: bar
        title: "VL Vector Abundance by Country"
        x: Country
        y:
          column: "Specie counts"
          aggregation: sum
        filters:
          - column: Form
            operator: "="
            value: VL
    map:
      lat: Lat
      lon: Lon
      fields:
        - species
        - Country
        - Form
        - "Specie counts"
        - Year
      clustering:
        enabled: true
        limit: 3000
      style:
        colorBy: Form
        sizeBy: "Specie counts"
        rules:
          - field: Form
            operator: "="
            value: VL
            color: "#ef4444"
            label: "VL Vectors"
          - field: Form
            operator: "="
            value: CL
            color: "#3b82f6"
            label: "CL Vectors"
      legend:
        title: "Vector Types"
        position: "bottomright"
    menus:
      about: |
        ## 🦟 Leishmaniasis Vector Surveillance Dashboard
        A comprehensive visualization platform for sand fly vector surveillance data...

🔌 API Reference

All API endpoints are available under the /qgd_api base path.

Authentication

• POST /token

  Get access token (username/password)

Dashboards

• GET /dashboards/

  List all dashboards (paginated)

• POST /dashboards/add

  Create a new dashboard

• GET /dashboards/{id}

  Get dashboard details

• PUT /dashboards/{id}/edit

  Rename dashboard

• POST /dashboards/{id}/delete

  Delete a dashboard

• PUT /dashboards/{id}/config

  Update dashboard YAML configuration

• POST /dashboards/{id}/add_data

  Upload data files (CSV/Excel)

Data Endpoints

• GET /dashboards/{id}/config

  Get dashboard configuration (public)

• GET /dashboards/{id}/points

  Get all map points as GeoJSON

• POST /dashboards/{id}/points-in-view

  Get points within bounding box (for clustering)

• POST /dashboards/{id}/chart-data

  Get aggregated data for a chart

• POST /dashboards/{id}/distinct-values

  Get distinct values for a column (for stacked charts)

• GET /dashboards/{id}/dashboard.js

  Get generated JavaScript config

• GET /dashboards/{id}/data-info

  Get data preview (rows, columns, sample)

• POST /dashboards/{id}/export

  Export filtered data as CSV

🛠️ Troubleshooting