1  Installation

Follow the steps below to install featuremap 1.0.0 (or a later version) from GitHub. The script first installs BiocManager and remotes if you don’t have them.

if (!requireNamespace("BiocManager", quietly = TRUE)) {
  install.packages("BiocManager")
}

if (!requireNamespace("remotes", quietly = TRUE)) {
  install.packages("remotes")
}

You also need to install some upstream dependencies from Github:

if (!requireNamespace("masstools", quietly = TRUE)) {
  remotes::install_github("tidymass/masstools")
}
if (!requireNamespace("massdataset", quietly = TRUE)) {
  remotes::install_github("tidymass/massdataset")
}
if (!requireNamespace("metid", quietly = TRUE)) {
  remotes::install_github("tidymass/metid")
}
if (!requireNamespace("pcsf2featuremap", quietly = TRUE)) {
  remotes::install_github("tidymass/pcsf2featuremap")
}

Then, install the featuremap and load it in your environment:

remotes::install_github(
  "tidymass/featuremap",
  dependencies = TRUE,
  repos = BiocManager::repositories(),
  upgrade = "ask"
)

library(featuremap)

On attachment, version 1.0.0 prints the workflow and a link to the package help page (the rule length may vary with terminal width):

── featuremap 1.0.0 ─────────────────────────
Metabolite annotation → Network extraction → Module identification → Function interpretation
ℹ Run `?featuremap` to get started.

To suppress this startup message in a script, set options(featuremap.quiet = TRUE) before calling library(featuremap).

After installation, run a quick check:

stopifnot(packageVersion("featuremap") >= "1.0.0")
packageVersion("featuremap")
# [1] ‘1.0.0’

citation("featuremap")

1.1 Reference Resources

FeatureMAP does not ship its large reference resources inside the package. The following resources are downloaded on demand from the featuremap_resources repository and then cached locally:

Resource Used by Content
featuremap_compound annotate_feature() Merged HMDB + KEGG MS1 compound database
mrn extract_subnetwork() Metabolic reaction network (MRN)
functional_reference_hmdb, functional_reference_kegg annotate_module() Compound class / functional metadata
pathway_hmdb, pathway_kegg annotate_module() Pathway membership used for coverage statistics

The first run of each step therefore needs an internet connection. Downloaded files are reused afterwards, so later runs work offline.

By default the cache lives in tools::R_user_dir("featuremap", which = "cache"). You can point it somewhere else, for example to a shared project folder:

options(featuremap.resources.cache_dir = "~/featuremap_cache")
Note

If your machine cannot reach GitHub, you can also download the resources manually and pass them directly through the corresponding arguments (metabolite_database, mrn, ref_data).

1.2 Optional: API Keys for Module Annotation

The last step of the workflow (Function Annotation) calls a large language model (LLM) and, optionally, PubMed. These services need API keys, which are not required for Steps 1–4.

Store them as environment variables instead of hard-coding them in your scripts. Add the following lines to your .Renviron file (open it with usethis::edit_r_environ()), then restart R:

OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxx
NCBI_API_KEY=xxxxxxxxxxxxxxxx

And use them like this:

Sys.getenv("OPENAI_API_KEY")
Sys.getenv("NCBI_API_KEY")

Supported LLM providers and where to apply for a key:

1.3 Next Step

If all checks pass, continue to Data Preparation to prepare the input tables for the FeatureMAP workflow.