Carbon Atlas

A small macOS/iOS SwiftUI app that visualizes per-country CO2 emissions on a map.

What this repo contains

• SwiftUI app sources (views, models, view models) that load GeoJSON country polygons and map CO2 emissions to country ISO codes.
• carbon_atlas.duckdb — a bundled DuckDB database used by the app to supply CO2 emissions data (legacy co2explorer.duckdb is also supported).
• countries.geojson — GeoJSON used to draw country polygons.

carbon_atlas.duckdb — contents and provenance

The bundled database file carbon_atlas.duckdb (or legacy co2explorer.duckdb) contains a single table named data (this is what the app queries).

• Table: data
• Number of columns: ~80 (many columns were imported from the public dataset)

Important columns (selection):

• Name (country/region name)
• iso_code (3-letter ISO country code, used by the app to join polygons to values)
• year (integer year)
• population (integer)

Carbon Atlas

A small macOS/iOS SwiftUI app that visualizes per-country CO2 emissions on an interactive map.

This project uses the Factory library for lightweight dependency injection.

Highlights (updated)

• Side menu with metric selector (open with the hamburger button). The menu slides in with a dimmed backdrop and small animations.
• Four user-selectable metrics (see "Metrics" below). Selecting a metric updates the map asynchronously for the currently selected year.
• Long-press any metric in the side menu to see a short description (alert dialog).
• Default year: 2020. Default metric: "Total yearly (Mt)".
• Geometry and color updates are animated for a smoother UX.

Sample screenshots

Below are sample screenshots included in the sample/ folder of the repository. These images are referenced directly from the GitHub repository so they will render on the README when viewed on GitHub.

App Demo

What this repo contains

• SwiftUI app sources (views, models, view models) that load GeoJSON country polygons and map CO2 emissions to country ISO codes.
• carbon_atlas.duckdb — a bundled DuckDB database used by the app to supply CO2 emissions data (legacy co2explorer.duckdb is also supported).
• countries.geojson — GeoJSON used to draw country polygons.

Metrics (user-facing)

The app exposes these metrics in the side menu (display label → short description):

• Total yearly (Mt) — Total yearly carbon dioxide emissions, excluding land‑use changes (million tonnes).
• Yearly increase (Mt) — Year‑over‑year change in total CO₂ emissions (million tonnes).
• Per‑capita (t/person) — CO₂ emissions per person for the selected year (tonnes/person).
• Cumulative (Mt) — Accumulated CO₂ emissions from the first available year onward (million tonnes).

Use the menu button (hamburger icon) to open the side menu, tap a metric to apply it, or long‑press a metric to see its description in an alert.

When a metric is selected the app calls the repository to fetch values for the selected year and recomputes polygon colors. Countries with no data for the chosen metric/year are drawn in gray.

How the app uses the DB

The app uses CO2Repository.swift to read per-year emissions and returns a mapping [iso_code: value] that MapViewModel uses to color polygons. MapViewModel performs parsing and color computation off the main thread where appropriate and publishes animated updates to the UI.

Key notes:

• Default selected year is 2020 (can be changed in MapViewModel).
• Default selected metric is .total (see CO2Metric.swift).
• Color mapping uses logarithmic scaling so colors remain informative across large ranges.

Testing

This project includes comprehensive unit tests and UI tests:

• Unit Tests: The project contains unit tests for core components including:

  • Repository layer (CO2RepositoryTests)
  • Dependency Injection (DITests)
  • GeoJSON parsing and loading (GeoJSONParserTests, GeoJSONLoaderTests)
  • Models and ViewModels (MapModelsTests, MapViewModelTests)

• UI Tests: The project has UI tests in progress, focusing on the map chart view functionality (MapChartViewUITests). UI test coverage is currently being expanded.

To run the tests, open the project in Xcode and press ⌘U or select Product > Test from the menu.

Quick local inspection (DuckDB CLI)

If you want to inspect the DB locally, install DuckDB and run these commands (zsh):

# open interactive duckdb shell for the file
duckdb '/path/to/carbon_atlas.duckdb'

# once inside duckdb shell, list tables
.tables

# inspect schema for `data`
PRAGMA table_info('data');

# sample rows
SELECT Name, iso_code, year, co2, co2_per_capita, population
FROM data
LIMIT 10;

Or single-shot:

duckdb '/path/to/carbon_atlas.duckdb' "PRAGMA table_info('data');"
duckdb '/path/to/carbon_atlas.duckdb' "SELECT Name, iso_code, year, co2 FROM data WHERE year=2019 LIMIT 50;"

Run (locally)

Open the Xcode project/workspace (co2emissions.xcodeproj or the workspace) and run the app on the desired platform (macOS or an iOS simulator). The app is implemented in SwiftUI and requires a recent Xcode that supports Swift concurrency (Xcode 14+/macOS 12+ recommended).

Dependency Injection (Factory)

This project uses the Factory library for lightweight dependency injection. To add it to the project:

1. In Xcode go to File → Add Packages...
2. Enter the package URL: https://github.com/hmlongco/Factory
3. Select the latest release and add it to the app target.

The DI registrations live in DI.swift via Container factories. For tests you can override factories like:

Container.co2Repository.register { MockCO2Repository() }

or use the withDependencies helper from Factory to temporarily override while running a test.

Recreating or updating the database

If you want to rebuild the DB from the Kaggle Data.csv file, a minimal import using DuckDB from the CSV would look like:

CREATE TABLE data AS SELECT * FROM read_csv_auto('Data.csv');

Be mindful of CSV encoding and column types. If desired, we can add a small import script to filter and produce a trimmed DuckDB file containing only the fields the app needs.

Notes & provenance

• The included carbon_atlas.duckdb (originally co2explorer.duckdb) was derived from a public CO₂ dataset (see original Kaggle link in previous commits). Verify the dataset's license before redistribution.
• The project code is MIT's license (see LICENSE).

Changes implemented in code (mapping to README)

• Side menu interactions: implemented in SideMenuView.swift (hamburger toggle, sliding panel, dim backdrop, menu width 260, long-press to show metric description).
• Metric definitions and display strings: CO2Metric.swift.
• Async loading and updates: MapViewModel.swift loads GeoJSON and fetches emissions off‑main where appropriate, then publishes animated updates.