Skip to contents

Advanced Workflow

Source: vignettes/advanced-workflow.qmd

This guide covers advanced usage patterns for managing the Artalytics platform ecosystem with artaverse.

Managing Package Updates

Check for Outdated Packages

Use artaverse_update() to check if newer versions are available on GitHub:

library(artaverse)

# Check all packages (core + extended)
artaverse_update()

This queries GitHub for the latest versions and compares them to what you have installed:

Checking for updates...
⚠ Updates available:

  artcore 1.2.0 -> 1.3.0
  artutils 0.18.0 -> 0.19.0

Update with: pak::pkg_install("artalytics/<package>")

Check Only Core Packages

If you only use core packages, skip extended packages to speed up the check:

artaverse_update(include_extended = FALSE)

Updating Packages

When updates are available, use pak to install them:

# Update a specific package
pak::pkg_install("artalytics/artcore")

# Or reinstall everything
pak::pkg_install("artalytics/artaverse")

After updating, verify versions:

Resolving Function Conflicts

Detecting Conflicts

When multiple packages export the same function name, the most recently loaded package “wins”. Use artaverse_conflicts() to identify these conflicts:

library(artaverse)

# Check for conflicts between artaverse packages
artaverse_conflicts()

If conflicts exist, you’ll see:

⚠ artaverse conflicts

artutils::get_artist() masks modArtist::get_artist()

Resolving Conflicts

Option 1: Use explicit namespacing (recommended)

# Be explicit about which function you want
artist <- artutils::get_artist(slug)  # Use artutils version
artist <- modArtist::get_artist(id)   # Use modArtist version

Option 2: Load packages in specific order

# Load packages individually in the order you want
library(modArtist)
library(artutils)  # This will mask modArtist::get_artist()

# Now get_artist() uses artutils version
artist <- get_artist(slug)

Check All Conflicts

To see conflicts with non-artaverse packages too:

artaverse_conflicts(only_artaverse = FALSE)

Analyzing Dependencies

Understanding Package Dependencies

Use artaverse_deps() to see all dependencies:

# Get all dependencies (recursive)
deps <- artaverse_deps()
deps

This returns a data.table showing: - Which artaverse package requires each dependency - The dependency type (Imports, Suggests, etc.) - Whether each dependency is installed

Non-Recursive Dependencies

To see only direct dependencies (not dependencies of dependencies):

deps_direct <- artaverse_deps(recursive = FALSE)

Finding Missing Dependencies

Identify which dependencies are missing:

deps <- artaverse_deps()

# Filter to missing dependencies
missing <- deps[installed == FALSE]
missing$dependency

Debugging Installation Issues

If package installation fails, check dependencies first:

# Check what's missing
deps <- artaverse_deps(include_extended = FALSE)
missing <- unique(deps[installed == FALSE, dependency])

if (length(missing) > 0) {
  message("Missing dependencies: ", paste(missing, collapse = ", "))

  # Install missing packages
  install.packages(missing)
}

Custom Installation Workflows

Dry Run Installation

Preview what would be installed without actually installing:

install_artaverse(
  installer = function(refs) {
    cat("Would install:\n")
    cat(paste("-", refs, collapse = "\n"))
  }
)

Custom Installation Function

Use a custom installer for testing or special requirements:

# Example: Install from a different GitHub org
custom_installer <- function(refs) {
  # Replace org name
  test_refs <- gsub("artalytics/", "myorg-fork/", refs)
  pak::pkg_install(test_refs)
}

install_artaverse(installer = custom_installer)

Programmatic Installation in Scripts

Use options to control installation behavior:

# Set option to always include extended packages
options(artaverse.install_extended = TRUE)

# Now install_artaverse() will include extended by default
install_artaverse()

Troubleshooting

Issue: Packages Won’t Load

Symptom: library(artaverse) shows packages failed to attach

Diagnosis:

# Check which packages are installed
versions <- artaverse_versions()
versions[is.na(version)]  # Not installed

versions[!is.na(version)]  # Installed

Solution:

# Reinstall missing packages
pak::pkg_install("artalytics/artaverse")

Issue: Wrong Package Versions

Symptom: Functions behave unexpectedly or don’t exist

Diagnosis:

# Check installed versions
artaverse_versions()

# Compare to latest available
artaverse_update()

Solution:

# Update specific packages
pak::pkg_install("artalytics/artcore")
pak::pkg_install("artalytics/artutils")

Issue: GitHub Authentication Errors

Symptom: Error: HTTP 401 when installing

Cause: Missing or invalid GITHUB_PAT

Solution:

# Check if GITHUB_PAT is set
Sys.getenv("GITHUB_PAT")

# If empty, set it (get token from GitHub)
Sys.setenv(GITHUB_PAT = "your_token_here")

# Then retry installation
pak::pkg_install("artalytics/artaverse")

Issue: Installation Hangs

Symptom: Installation takes forever or appears stuck

Diagnosis:

# Check which dependencies are needed
deps <- artaverse_deps()
nrow(deps)  # Total dependencies

Solution: Be patient - first installation can take 5-10 minutes with ~180 packages. Or install core only:

install_artaverse(include_extended = FALSE)

CI/CD Integration

GitHub Actions Workflow

Use artaverse in automated workflows:

name: Test with Artalytics

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: r-lib/actions/setup-r@v2
        with:
          r-version: 'release'

      - name: Install artaverse
        run: |
          install.packages('pak')
          pak::pkg_install('artalytics/artaverse')
        shell: Rscript {0}
        env:
          GITHUB_PAT: ${{ secrets.GITHUB_PAT }}

      - name: Run tests
        run: |
          library(artaverse)
          # Your test code here
        shell: Rscript {0}

Docker Integration

Create a Dockerfile with artaverse pre-installed:

FROM rocker/r-ver:4.3.0

# Install system dependencies
RUN apt-get update && apt-get install -y \
    libcurl4-openssl-dev \
    libssl-dev \
    libxml2-dev

# Install pak
RUN R -e "install.packages('pak')"

# Install artaverse
ARG GITHUB_PAT
ENV GITHUB_PAT=$GITHUB_PAT
RUN R -e "pak::pkg_install('artalytics/artaverse')"

# Your app code
COPY . /app
WORKDIR /app

Build with:

docker build --build-arg GITHUB_PAT=$GITHUB_PAT -t myapp .

Advanced Package Discovery

Finding Functions by Pattern

Combine artaverse_packages() with package inspection:

library(artaverse)

# Get all core packages
core <- artaverse_core()

# Find all exported functions in core packages
all_functions <- lapply(core, function(pkg) {
  if (requireNamespace(pkg, quietly = TRUE)) {
    exports <- getNamespaceExports(pkg)
    data.frame(package = pkg, function_name = exports)
  }
})

all_funs <- do.call(rbind, all_functions)

# Find functions matching a pattern
grep("^get_", all_funs$function_name, value = TRUE)

Package Load Order

The order packages are loaded matters for conflicts. Check current order:

# See what's on the search path
search()

# artaverse packages will be listed as "package:pkgname"
grep("^package:(art|mod|app)", search(), value = TRUE)

Performance Optimization

Lazy Loading

Only load packages you need for specific tasks:

# Instead of library(artaverse), load selectively
library(artcore)  # Just database access
library(artutils) # Just data utilities

# Use :: for occasional functions
stats <- artutils::get_artist_stats(artist)

Reducing Startup Time

Suppress startup messages in scripts:

Caching Package Lists

Cache expensive operations:

# Cache package lists
.artaverse_cache <- new.env(parent = emptyenv())

get_cached_packages <- function() {
  if (is.null(.artaverse_cache$packages)) {
    .artaverse_cache$packages <- artaverse_packages()
  }
  .artaverse_cache$packages
}

Summary

artaverse provides powerful tools for managing the Artalytics platform ecosystem:

These functions enable sophisticated workflows for development, testing, and production deployment of Artalytics applications.