traderoutes for R

traderoutes provides country-border queries and weighted shortest-path trade routes on a worldwide road, port, and shipping network.

The R package bundles compressed, R-native igraph objects under inst/extdata/. Users do not need the graph-generation code or a container to install and use the package.

Installation

Install the latest published version from R-universe with:

install.packages(
  "traderoutes",
  repos = c(
    "https://milonemario.r-universe.dev",
    "https://cloud.r-project.org"
  )
)

To install a specific tagged version directly from GitHub, install remotes and specify the repository tag and the R-package subdirectory:

install.packages("remotes")

remotes::install_github(
  "milonemario/traderoutes",
  ref = "v0.0.3",
  subdir = "traderoutes-r"
)

The v0.0.3 tag refers to the shared repository release. Replace it with another Git tag or commit when installing a different version.

For local development, install the source package with:

install.packages("/path/to/traderoutes-r", repos = NULL, type = "source")

The package requires R 4.1 or newer and imports igraph.

Quick start

library(traderoutes)

are_neighbors("FRA", "ITA")
get_neighbors("FRA")
get_common_neighbors("FRA", "ITA")

origin <- get_main_city("FRA")
destination <- get_main_city("NLD")
path <- get_path(origin, destination, road_cost = 7, port_cost = 1e4)

get_pattern(path)
road_distance(path)
sea_distance(path)
transits_i(path)
transits_j(path)

Package data

The package expects these files under inst/extdata/:

inst/extdata/bordersgraph.rds
inst/extdata/fullgraph.rds

The RDS files are generated from the canonical GraphML outputs in graph/. The conversion tool is development-only and is excluded from the package source tarball. Run it from this directory with the build environment:

podman run --rm \
  -v "$PWD:/workspace:Z" \
  -v "$PWD/../graph:/graph:ro,Z" \
  traderoutes-r-build-env \
  Rscript /workspace/tools/convert_graphml_to_rds.R \
    --input-dir /graph/FullGraph \
    --output-dir /workspace/inst/extdata

Verify that the generated files exist and inspect their sizes:

ls -lh inst/extdata/*.rds

Once the RDS files have been generated successfully, remove the temporary GraphML copies from the R package directory. Keep the canonical GraphML files under ../graph/FullGraph/:

rm -- inst/extdata/bordersgraph.graphml inst/extdata/fullgraph.graphml

The package should contain the RDS files before running the test or build stages. The conversion step must be repeated whenever the canonical graphs change. During conversion, package-unused vertex attributes are removed and the RDS files are written with maximum XZ compression.

After conversion, the RDS files are large and should be stored through Git LFS. Retrieve the actual objects before building:

git lfs pull

Podman targets

The Dockerfile provides reproducible development, testing, and build environments. Build from this directory:

podman build --target build-env -t traderoutes-r-build-env .
podman build --target test -t traderoutes-r-test .
podman build --target build -t traderoutes-r-build .

The stages have different purposes:

The test stage runs its tests during podman build, so a failing test causes the image build to fail. It also has the test command as its default container command, so a successful image can be tested again:

podman run --rm traderoutes-r-test

Local tests

With R, igraph, and testthat installed, run the source-tree tests with:

Rscript --vanilla -e 'testthat::test_local(".")'

To build and check the release tarball in the Podman build environment while writing the artifact directly to the host:

mkdir -p dist

podman run --rm \
  -v "$PWD:/workspace:Z" \
  -v "$PWD/dist:/out:Z" \
  traderoutes-r-build-env \
  sh -c 'cd /out && \
    Rscript --vanilla -e "roxygen2::roxygenise(\"/workspace\")" && \
    R CMD build --no-manual --no-build-vignettes /workspace && \
    R CMD check --no-manual --no-vignettes \
      --no-build-vignettes traderoutes_*.tar.gz'

Install and smoke-test the exact checked tarball:

podman run --rm \
  -v "$PWD/dist:/dist:Z" \
  traderoutes-r-build-env \
  sh -c 'R CMD INSTALL /dist/traderoutes_0.0.3.tar.gz && \
    Rscript --vanilla -e "library(traderoutes); print(head(countries()))"'

For a stricter CRAN-style check, run:

mkdir -p cran-check

podman run --rm \
  -v "$PWD:/workspace:Z" \
  -v "$PWD/cran-check:/out:Z" \
  traderoutes-r-build-env \
  sh -c 'cd /out && R CMD check --as-cran /workspace/dist/traderoutes_0.0.3.tar.gz'

Use a fresh cran-check directory for each run. This prevents an old .Rcheck directory from being reused and confusing the result.

Replace 0.0.3 in these commands if the package version changes. The --as-cran check should pass without errors or warnings before a CRAN submission is considered.

Main API

Function Description
are_neighbors(c1, c2) Whether two countries share a land border
get_neighbors(c) Neighboring ISO3 country codes
get_second_neighbors(c) Countries two border hops away
get_common_neighbors(c1, c2) Countries neighboring both inputs
countries() Countries represented in the transportation graph
get_main_city(c) Main city vertex for a country
get_great_circle(c1, c2) Great-circle distance in km
get_path(v1, v2, ...) Weighted shortest path
get_pattern(path) Compact path vertex-type pattern
get_countries(path, ...) Country segments and distances
road_distance(path) Road distance in km
sea_distance(path) Sea distance in km
transits_i(path, ...) Origin-side transit countries
transits_j(path, ...) Destination-side transit countries

License

MIT; see LICENSE.