Skip to contents

Upon completion of the MetaScope pipeline, users can analyze and visualize abundances in their samples using the animalcules package. This function allows interoperability of metascope_id output with both animalcules and QIIME. After running this function, the user should save the returned MAE to an RDS file using a function like saveRDS to upload the output into the animalcules package.


  end_string = ".metascope_id.csv",
  qiime_biom_out = FALSE,
  path_to_write = ".",
  NCBI_key = NULL,
  num_tries = 5



A vector of filepaths to the counts ID CSVs output by metascope_id().


The filepath to the CSV annotation file for the samples.


The name of the column of the annotation file containing the sample IDs. These should be the same as the meta_counts root filenames.


The end string used at the end of the metascope_id files. Default is ".metascope_id.csv".


Would you also like a qiime-compatible biom file output? If yes, two files will be saved: one is a biom file of the counts table, and the other is a specifically formatted mapping file of metadata information. Default is FALSE.


If qiime_biom_out = TRUE, where should output QIIME files be written? Should be a character string of the folder path. Default is '.', i.e. the current working directory.


(character) NCBI Entrez API key. optional. See taxize::use_entrez(). Due to the high number of requests made to NCBI, this function will be less prone to errors if you obtain an NCBI key.


(numeric) Number of attempts to get UID.


Returns a multi-assay experiment file of combined sample counts data and/or biom file and mapping file for analysis with QIIME. The multi-assay experiment will have assays for the counts ("MGX"), log counts, CPM, and log CPM.


tempfolder <- tempfile()

# Create three different samples
samp_names <- c("X123", "X456", "X789")
all_files <- file.path(tempfolder,
                       paste0(samp_names, ".csv"))

create_IDcsv <- function (out_file) {
  final_taxids <- c("273036", "418127", "11234")
  final_genomes <- c(
    "Staphylococcus aureus RF122, complete sequence",
    "Staphylococcus aureus subsp. aureus Mu3, complete sequence",
    "Measles virus, complete genome")
  best_hit <- sample(seq(100, 1050), 3)
  proportion <- best_hit/sum(best_hit) |> round(2)
  EMreads <- best_hit + round(runif(3), 1)
  EMprop <- proportion + 0.003
  dplyr::tibble(TaxonomyID = final_taxids,
                Genome = final_genomes,
                read_count = best_hit, Proportion = proportion,
                EMreads = EMreads, EMProportion = EMprop) |>
    dplyr::arrange(dplyr::desc(.data$read_count)) |>
    utils::write.csv(file = out_file, row.names = FALSE)
out_files <- vapply(all_files, create_IDcsv, FUN.VALUE = character(1))
#> Done!
#> Done!
#> Done!

# Create annotation data for samples
annot_dat <- file.path(tempfolder, "annot.csv")
dplyr::tibble(Sample = samp_names, RSV = c("pos", "neg", "pos"),
              month = c("March", "July", "Aug"),
              yrsold = c(0.5, 0.6, 0.2)) |>
  utils::write.csv(file = annot_dat,
                   row.names = FALSE)

# Convert samples to MAE
outMAE <- convert_animalcules(meta_counts = out_files,
                              annot_path = annot_dat,
                              which_annot_col = "Sample",
                              end_string = ".metascope_id.csv",
                              qiime_biom_out = FALSE,
                              path_to_write = tempfolder,
                              NCBI_key = NULL)
#> Looking up taxon UIDs in NCBI database
  |                                                                      |   0%
#> No ENTREZ API key provided
#>  Get one via taxize::use_entrez()
#> See
  |=======================                                               |  33%
#> No ENTREZ API key provided
#>  Get one via taxize::use_entrez()
#> See
  |===============================================                       |  67%
#> No ENTREZ API key provided
#>  Get one via taxize::use_entrez()
#> See
  |======================================================================| 100%

unlink(tempfolder, recursive = TRUE)