Wilderlab API User Manual

1. Installation

The wilderlab R package contains functions for importing and exporting eDNA data. To download the package from GitHub, ensure that devtools is installed. The insect package will also be required later on in this tutorial:

if(!("devtools" %in% list.files(.libPaths()))) install.packages("devtools")
if(!("insect" %in% list.files(.libPaths()))) install.packages("insect")

Then run:

devtools::install_github("wilderlabnz/wilderlab") 
library(wilderlab)

2. Load access keys

When signing up to the Wilderlab API, your unique log in information will be securely sent to you. This will include three access keys: an API access key id, key; a secret access key, secret; and a X-API-Key, xapikey.
Copy and paste this unique information into the appropriate slots in the following code to load them into your R session.

key <- "*****************"
secret <- "***************************************"
xapikey <- "***************************************"

3. get_wilderdata function

get_wilderdata(tb, key, secret, xapikey, JobID = NULL)

4. Get data tables

Pulling information from the job, samples, and taxa tables is very straightforward. All the information associated with a unique API access key is accessed as a whole:

jobs <- get_wilderdata("jobs", key = key, secret = secret, xapikey = xapikey)
samples <- get_wilderdata("samples", key = key, secret = secret, xapikey = xapikey)
taxa <- get_wilderdata("taxa", key = key, secret = secret, xapikey = xapikey)

Pulling from the records table is done on a specified JobID thus multiple calls must be made to get a full records table. After accessing the jobs table, the relevant JobIDs can be iterated over, the corresponding records pulled through the API, and finally the gathered records combined into a complete records table. The following code chunk is an example of how this can be done.

records <- vector(mode = "list", length = nrow(jobs))
for(i in seq_along(records)){
  records[[i]] <- get_wilderdata("records", JobID = jobs$JobID[i],
                                 key = key, secret = secret, xapikey = xapikey)
}
records <- do.call("rbind", records)

5. Fill lineage information

The final step in completing the records table is to add lineage information and sample metadata. This is an optional step but can improve interpretation of the results.

tdb <- taxa[, 1:4]
colnames(tdb) <- c("taxID", "parent_taxID", "rank", "name")
lineages = insect::get_lineage(records$TaxID, tdb)
records$phylum <- sapply(lineages, "[", "phylum")
records$class <- sapply(lineages, "[", "class")
records$order <- sapply(lineages, "[", "order")
records$family <- sapply(lineages, "[", "family")
records$genus <- sapply(lineages, "[", "genus")
records$species <- sapply(lineages, "[", "species")
records$Latitude <- samples$Latitude[match(records$UID,samples$UID)]
records$Longitude <- samples$Longitude[match(records$UID,samples$UID)]
records$ClientSampleID <- samples$ClientSampleID[match(records$UID,samples$UID)]

Jobs

Getting information from the jobs table:

jobs <- get_wilderdata("jobs", key = key, secret = secret, xapikey = xapikey)
jobs

   JobID SubmissionDate     ContactName    ContactEmail PurchaseOrder                          JobReference JobNotes NumberOfSamples          AssayPanel MakeDataPublic PassCode JobStatus                                                                                                      ResultsLink InvoiceNo
1 601833     2021-07-04 Shaun Wilkinson api@example.com               Passive sampler validation experiment                        3 Comprehensive panel              1  W1E0638  Complete https://s3.ap-southeast-2.amazonaws.com/wilderlab.results/c03d243992534adcf4ffecd39c43d6e8/WLM601833_250626.xlsx  INTERNAL
2 601834     2021-07-04 Shaun Wilkinson api@example.com               Passive sampler validation experiment                        3 Comprehensive panel              1  W1E0638  Complete https://s3.ap-southeast-2.amazonaws.com/wilderlab.results/a26f9576e52ce92c689070da34865104/WLM601834_250626.xlsx  INTERNAL

Samples

Getting information from the samples table:

samples <- get_wilderdata("samples", key = key, secret = secret, xapikey = xapikey)
samples

   SID  JobID    UID CollectionDate     CollectedBy   ClientSampleID   Latitude  Longitude VolumeFilteredML DeploymentDuration EnvironmentType   TICI TICINoSeqs TICIQuantile        TICIVersion   ClientNotes      AccountName MakeDataPublic                                                                                     Report
1 8145 601833 507875     2021-07-03 Shaun Wilkinson Ruakokoputuna C3 -41.312665 175.449873             1000                       River/Stream 105.80        109         0.57        Riverine V1 Control rep 3 Wilderlab NZ Ltd              1 https://s3.ap-southeast-2.amazonaws.com/wilderlab.openwaters/reports/c62322f1b3162646.html
2 8143 601833 507877     2021-07-03 Shaun Wilkinson Ruakokoputuna C1 -41.312665 175.449873             1000                       River/Stream   0.00          0         0.00 NC - Low seq count Control rep 1 Wilderlab NZ Ltd              1 https://s3.ap-southeast-2.amazonaws.com/wilderlab.openwaters/reports/c62322f1b3162646.html
3 8144 601833 510042     2021-07-03 Shaun Wilkinson Ruakokoputuna C2 -41.312665 175.449873             1000                       River/Stream 100.08        159         0.51        Riverine V1 Control rep 2 Wilderlab NZ Ltd              1 https://s3.ap-southeast-2.amazonaws.com/wilderlab.openwaters/reports/c62322f1b3162646.html
4 8146 601834 510897     2021-07-03 Shaun Wilkinson Ruakokoputuna P1 -41.312665 175.449873                                  24    River/Stream 100.97        391         0.52        Riverine V1 Passive rep 1 Wilderlab NZ Ltd              1 https://s3.ap-southeast-2.amazonaws.com/wilderlab.openwaters/reports/0b6f40128711495a.html
5 8147 601834 510898     2021-07-03 Shaun Wilkinson Ruakokoputuna P2 -41.312665 175.449873                                  24    River/Stream 100.88        381         0.52        Riverine V1 Passive rep 2 Wilderlab NZ Ltd              1 https://s3.ap-southeast-2.amazonaws.com/wilderlab.openwaters/reports/0b6f40128711495a.html
6 8148 601834 510899     2021-07-03 Shaun Wilkinson Ruakokoputuna P3 -41.312665 175.449873                                  24    River/Stream  99.81        320         0.50        Riverine V1 Passive rep 3 Wilderlab NZ Ltd              1 https://s3.ap-southeast-2.amazonaws.com/wilderlab.openwaters/reports/0b6f40128711495a.html

Taxa

Getting information from the taxa table:

taxa <- get_wilderdata("taxa", key = key, secret = secret, xapikey = xapikey)
head(taxa, 10)

   TaxID ParentTaxID    Rank             Name                CommonName MaoriName
1      1           0 no rank             root              Unidentified          
2      2      131567  domain         Bacteria                Eubacteria          
3      6      335928   genus     Azorhizobium                                    
4     10     1706371   genus       Cellvibrio                                    
5     13      203488   genus     Dictyoglomus                                    
6     18      213421   genus       Pelobacter                                    
7     20       76892   genus Phenylobacterium                                    
8     22      267890   genus       Shewanella                                    
9     29       32015   order     Myxococcales Fruiting gliding bacteria          
10    31       80811  family    Myxococcaceae                                    

Records

Getting information from the records table:

records <- vector(mode = "list", length = nrow(jobs))
for(i in seq_along(records)){
  records[[i]] <- get_wilderdata("records", JobID = jobs$JobID[i],
                                 key = key, secret = secret, xapikey = xapikey)
}
records <- do.call("rbind", records)

head(records, 10)

       HID    UID TaxID   Rank               Name CommonName    Group Count
1  2557713 507875    10  genus         Cellvibrio            Bacteria    37
2  2679827 510042    10  genus         Cellvibrio            Bacteria    43
3  2557718 507875   237  genus     Flavobacterium            Bacteria    62
4  2679837 510042   237  genus     Flavobacterium            Bacteria    21
5  2557710 507875   444 family     Legionellaceae            Bacteria    42
6  2557724 507875   543 family Enterobacteriaceae            Bacteria    20
7  2557748 507877   543 family Enterobacteriaceae            Bacteria     7
8  2679838 510042   543 family Enterobacteriaceae            Bacteria    20
9  2679848 510042   642  genus          Aeromonas            Bacteria     6
10 2679844 510042   978  genus          Cytophaga            Bacteria     9

Adding lineage information and sample metadata information into the records table:

tdb <- taxa[, 1:4]
colnames(tdb) <- c("taxID", "parent_taxID", "rank", "name")
lineages = insect::get_lineage(records$TaxID, tdb)
records$phylum <- sapply(lineages, "[", "phylum")
records$class <- sapply(lineages, "[", "class")
records$order <- sapply(lineages, "[", "order")
records$family <- sapply(lineages, "[", "family")
records$genus <- sapply(lineages, "[", "genus")
records$species <- sapply(lineages, "[", "species")
records$Latitude <- samples$Latitude[match(records$UID, samples$UID)]
records$Longitude <- samples$Longitude[match(records$UID, samples$UID)]
records$ClientSampleID <- samples$ClientSampleID[match(records$UID, samples$UID)]

head(records, 10)

       HID    UID TaxID   Rank               Name CommonName    Group Count         phylum               class            order             family          genus species   Latitude  Longitude   ClientSampleID
1  2557713 507875    10  genus         Cellvibrio            Bacteria    37 Pseudomonadota Gammaproteobacteria  Cellvibrionales   Cellvibrionaceae     Cellvibrio    <NA> -41.312665 175.449873 Ruakokoputuna C3
2  2679827 510042    10  genus         Cellvibrio            Bacteria    43 Pseudomonadota Gammaproteobacteria  Cellvibrionales   Cellvibrionaceae     Cellvibrio    <NA> -41.312665 175.449873 Ruakokoputuna C2
3  2557718 507875   237  genus     Flavobacterium            Bacteria    62   Bacteroidota      Flavobacteriia Flavobacteriales  Flavobacteriaceae Flavobacterium    <NA> -41.312665 175.449873 Ruakokoputuna C3
4  2679837 510042   237  genus     Flavobacterium            Bacteria    21   Bacteroidota      Flavobacteriia Flavobacteriales  Flavobacteriaceae Flavobacterium    <NA> -41.312665 175.449873 Ruakokoputuna C2
5  2557710 507875   444 family     Legionellaceae            Bacteria    42 Pseudomonadota Gammaproteobacteria    Legionellales     Legionellaceae           <NA>    <NA> -41.312665 175.449873 Ruakokoputuna C3
6  2557724 507875   543 family Enterobacteriaceae            Bacteria    20 Pseudomonadota Gammaproteobacteria Enterobacterales Enterobacteriaceae           <NA>    <NA> -41.312665 175.449873 Ruakokoputuna C3
7  2557748 507877   543 family Enterobacteriaceae            Bacteria     7 Pseudomonadota Gammaproteobacteria Enterobacterales Enterobacteriaceae           <NA>    <NA> -41.312665 175.449873 Ruakokoputuna C1
8  2679838 510042   543 family Enterobacteriaceae            Bacteria    20 Pseudomonadota Gammaproteobacteria Enterobacterales Enterobacteriaceae           <NA>    <NA> -41.312665 175.449873 Ruakokoputuna C2
9  2679848 510042   642  genus          Aeromonas            Bacteria     6 Pseudomonadota Gammaproteobacteria    Aeromonadales     Aeromonadaceae      Aeromonas    <NA> -41.312665 175.449873 Ruakokoputuna C2
10 2679844 510042   978  genus          Cytophaga            Bacteria     9   Bacteroidota          Cytophagia     Cytophagales      Cytophagaceae      Cytophaga    <NA> -41.312665 175.449873 Ruakokoputuna C2