---
title: "Introduction"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Introduction}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---




```r
library(matos)
```


## List available files

First, `list_projects` returns the [project page](https://matos.asascience.com/project), which is useful to figure out what URLs are associated with each project. You do not need MATOS permissions in order to view this page.


```r
all_projects <- list_projects()

head(all_projects)
#>                                   name number
#> 1                            ACK Array    168
#> 2  APG Atlantic and Shortnose Sturgeon    176
#> 3 ASI - White Shark Study, Montauk, NY    211
#> 4                   ASI Acoustic Array    100
#> 5              ASI Spinner Shark Study    227
#> 6   ASI White Shark Study, Southern NE    232
#>                                               url
#> 1 https://matos.asascience.com/project/detail/168
#> 2 https://matos.asascience.com/project/detail/176
#> 3 https://matos.asascience.com/project/detail/211
#> 4 https://matos.asascience.com/project/detail/100
#> 5 https://matos.asascience.com/project/detail/227
#> 6 https://matos.asascience.com/project/detail/232
```

I can also view the files that I've uploaded to my projects using `list_project_files`, but that requires logging in first. The family of `list_` functions in this package will prompt you to log in before moving on. Note that I'll be entering my MATOS username and password behind the scenes here.


```r
project_files <- list_project_files(project = 'umces boem offshore wind energy')
#> ! Please log in.
#> ✔ Login successful!

head(project_files)
#>   project                                file_type upload_date
#> 1      87 Deployed Receivers – Deployment Metadata  2020-03-30
#> 2      87               Tag Detections - .vfl file  2020-05-28
#> 3      87               Tag Detections - .vfl file  2020-05-28
#> 4      87               Tag Detections - .vfl file  2020-05-28
#> 5      87               Tag Detections - .vfl file  2020-05-28
#> 6      87               Tag Detections - .vfl file  2020-05-28
#>                      file_name
#> 1 BOEM_metadata_deployment.xls
#> 2  VR2AR_546455_20170328_1.vrl
#> 3  VR2AR_546456_20170328_1.vrl
#> 4  VR2AR_546457_20170329_1.vrl
#> 5  VR2AR_546458_20170329_1.vrl
#> 6  VR2AR_546459_20170328_1.vrl
#>                                                      url
#> 1  https://matos.asascience.com/projectfile/download/375
#> 2 https://matos.asascience.com/projectfile/download/1810
#> 3 https://matos.asascience.com/projectfile/download/1811
#> 4 https://matos.asascience.com/projectfile/download/1812
#> 5 https://matos.asascience.com/projectfile/download/1813
#> 6 https://matos.asascience.com/projectfile/download/1814
```

### User credentials
A side note on your MATOS username and password: `matos` defaults to asking you for your login credentials every time you start a new session. To skirt around this you can use `set_matos_credentials()`, which installs your username and password in your [.Renviron file](https://rstats.wtf/r-startup.html#renviron). You will be automatically logged in every time you use your current computer after doing this, but beware: someone else could theoretically access your username and password if they gain access to your computer.

### Back to the regularly-scheduled programming
I can also list any of my OTN node *Data Extraction Files*.


```r
ACT_MATOS_files <- list_extract_files(project = 'umces boem offshore wind energy',
                                      detection_type = 'all')

head(ACT_MATOS_files)
#>   project            file_type detection_type detection_year
#> 1      87 Data Extraction File        matched           2017
#> 2      87 Data Extraction File        matched           2018
#> 3      87 Data Extraction File        matched           2019
#> 4      87 Data Extraction File        matched           2020
#> 5      87 Data Extraction File        matched           2021
#> 6      87 Data Extraction File        matched           2022
#>   upload_date                         file_name
#> 1  2023-07-06 mdwea_matched_detections_2017.zip
#> 2  2023-07-06 mdwea_matched_detections_2018.zip
#> 3  2023-07-06 mdwea_matched_detections_2019.zip
#> 4  2023-07-06 mdwea_matched_detections_2020.zip
#> 5  2023-07-06 mdwea_matched_detections_2021.zip
#> 6  2023-07-06 mdwea_matched_detections_2022.zip
#>                                                                url
#> 1 https://matos.asascience.com/projectfile/downloadExtraction/87_1
#> 2 https://matos.asascience.com/projectfile/downloadExtraction/87_2
#> 3 https://matos.asascience.com/projectfile/downloadExtraction/87_3
#> 4 https://matos.asascience.com/projectfile/downloadExtraction/87_4
#> 5 https://matos.asascience.com/projectfile/downloadExtraction/87_5
#> 6 https://matos.asascience.com/projectfile/downloadExtraction/87_6
```


## Download project or data extraction files

There are a few ways to download the different types of files held by MATOS. I can download directly if I know the URL of the file:


```r
project_files$url[1]
#> [1] "https://matos.asascience.com/projectfile/download/375"

get_project_file(url = project_files$url[1])
#> 
#> ── Downloading files ──────────────────────────────────────────────
#> ✔ File(s) saved to:
#>    C:\Users\darpa2\Analysis\matos\vignettes\BOEM_metadata_deployment.xls
#> 
#> ── Unzipping files ────────────────────────────────────────────────
#> [1] "C:\\Users\\darpa2\\Analysis\\matos\\vignettes\\BOEM_metadata_deployment.xls"
```

I can download by using an index from the `ACT_MATOS_files` table above, here the file on the second row.


```r
get_extract_file(file = 2, project = 'umces boem offshore wind energy')
#> 
#> ── Downloading files ──────────────────────────────────────────────
#> ✔ File(s) saved to:
#>    C:\Users\darpa2\Analysis\matos\vignettes\mdwea_matched_detections_2018.zip
#> 
#> ── Unzipping files ────────────────────────────────────────────────
#> ✔ File(s) unzipped to:
#>    C:/Users/darpa2/Analysis/matos/vignettes/mdwea_matched_detections_2018.csv
#>    C:/Users/darpa2/Analysis/matos/vignettes/data_description.txt
#> [1] "C:/Users/darpa2/Analysis/matos/vignettes/mdwea_matched_detections_2018.csv"
#> [2] "C:/Users/darpa2/Analysis/matos/vignettes/data_description.txt"
```

## Search and download tag detections

Using the `tag_search` function, I can interface with MATOS' [tag search page](https://matos.asascience.com/search). Be very careful with this function -- it can take a *very*, **VERY** long time to return your files. This function downloads the requested CSV into your working directory, and, if `import = T` is used, reads it into your R session.


```r
my_detections <- tag_search(tags = paste0('A69-1601-254', seq(60, 90, 1)),
                            start_date = '03/01/2016',
                            end_date = '04/01/2016', 
                            import = T)
```

## Upload files to MATOS

There are times when you want to upload new data to MATOS. The currently accepted data types and formats are:

- newly-deployed transmitters (CSV/XLS(X))
- detection logs (CSV/VRL)
- receiver and glider deployment metadata (CSV/XLS(X))
- receiver events like temperature, tilt, etc. (CSV)
- glider GPS tracks (CSV)

A few data types use designated Ocean Tracking Network templates:

- tag metadata
- receiver deployment metadata
- glider deployment metadata

If you don't have one of these templates downloaded, you can download it through the package. For example:

```r
get_otn_template('glider')
```

Then, get to uploading!

```r
upload_file(project = 'umces boem offshore wind energy',
            file = c('this_is_a_dummy_file.csv', 'so_is_this.csv'),
            data_type = 'new_tags')
```

