ARTIS Model (Aquatic Resource Trade In Species)

This repository contains the ARTIS model codebase. This is where the Seafood Globalization team develops and maintains the ARTIS model, end-users will typically not need to follow the instalation instructions below.

ARTIS reconstructs global seafood supply chains by tracing trade flows and production data through a multi-stage allocation process. It enables detailed analysis of seafood consumption by country, species, and product form.

What’s New in v1.2.0

• Updated fishmeal preference species list based on industry reports and grey literature.
• See CHANGELOG for details

Model Overview

ARTIS reconstructs seafood supply chains by:

• Integrating production data, international trade flows, and processing factors.
• Disaggregating national production to detailed product codes using trade proportions.
• Tracing each product through exports, imports, processing, and consumption pathways.
• Providing per-country, per-species, and per-product estimates of seafood availability and use.

For full conceptual diagrams and methods, see the ARTIS Manual.

Run Modes

• local: Run ARTIS on your local machine. Used for specific HS versions/years runs. Requires significant compute resources and is developed/tested on macOS with ARM64 (Apple Silicon) architecture.
• demo: Fast, small test dataset for local runs and troubleshooting. (has not been maintained or checked recently)
• aws: Large-scale cloud runs on AWS Batch. See artis-hpc for details.

Installation

Prerequisites

• Python 3.11.x (Download)
• R (tested with R 4.2.2) (Download)
• RStudio (Download)

Python Environment

python3 -m venv /path/to/your/venv --without-scm-ignore-files
source venv/bin/activate
pip install -r requirements.txt
pip list  # confirm: qpsolvers, quadprog, cvxopt

artis R Package Installation

• Get a local copy of the latest ARTIS release from Github

$gh repo clone Seafood-Globalization-Lab/artis-model

• install the R package from the project root directory

devtools::install()

FIXIT: Need instructions to run model locally

Development Workflow

Branch Structure

• main: Stable releases
• develop: Ongoing development
• Task branches: develop-* (short-lived, merged back to develop)
• Hotfixes: branch from main for urgent fixes, merged back to main

Branch Workflow Diagram

gitGraph
   commit id: "v1.0"
   branch develop
   commit
   branch develop-ingest-new-data-v2
   commit id: "clean FAO"
   commit id: "resolve sciname"
   checkout develop
   merge develop-ingest-new-data-v2 id: "merge cleaning script"
   checkout develop
   commit id: "update README"
   branch develop-fix-bug
   commit
   checkout develop
   merge develop-fix-bug id: "merge fix-bug"
   commit id: "add documentation"
   checkout main
   merge develop id: "v2.0 Release"
   branch hot-fix
   checkout hot-fix
   commit id: "forgot this tiny thing"
   checkout main
   merge hot-fix id: "v2.0.1 Release"

Loading

System Requirements

Note: See requirements.txt for Python package versions. R package versions still require additional documentation.

• Platform: macOS Ventura 13.3.1 (ARM64/M1/M2 strongly recommended)
• R version: 4.2.2
• Python version: 3.11.x
• Key R packages: data.table, dplyr, stringr, tidyverse, reticulate, etc. See .renv_lock file for package version details
• Key Python packages: qpsolvers, quadprog, cvxopt

Citation

A formal dataset DOI will be posted here after the v1.1.0 release.
For now, cite the software as:

Jessica Gephart, Rahul Agrawal Bejarano, Althea Marks, & Kelvin Gorospe. (2024).
ARTIS input data and model. Knowledge Network for Biocomplexity. doi:10.5063/F1862DXT.

@software{artis-v1.2.0,
  title        = {ARTIS Model (Aquatic Resource Trade In Species), v1.2.0},
  author       = {Gephart, Jessica and Agrawal Bejarano, Rahul and Marks, Althea and Gorospe, Kelvin},
  year         = {2025},
  version      = {1.2.0},
  url          = {https://github.com/Seafood-Globalization-Lab/artis-model},
  note         = {Accessed: yyyy-mm-XX},
  institution  = {University of Washington},
  organization = {Seafood Globalization Lab},
  howpublished = {GitHub repository}
}

More Information

• ARTIS Manual: Conceptual background, methods, output structure, data access.
• ARTIS Wiki: Table descriptions, data sources, developer notes.
• CHANGELOG: Complete change history.

Model Visual Schematic

The following diagrams illustrate the core logic and processing steps of the ARTIS model:

• Disaggregating Trade Records:
  
  Shows how national-level production is mapped onto detailed product (HS) codes using trade information.

• Aggregating Trade Records Back Up:
  
  Demonstrates how disaggregated product flows are traced and summed back up to reconstruct consumption and trade balances.

• Consumption Workflow:
  
  Depicts the multi-stage allocation process: from production and trade through to final consumption estimates.

• Codebase Structure Diagrams:
  
  
  
  Visuals of the ARTIS codebase organization and major workflow steps.