--- title: "LNWorkshopExample_TOV-E_Metadata" output: rmarkdown::html_vignette vignette: > %\VignetteIndexEntry{LNWorkshopExample_TOV-E_Metadata} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- ```{r, include = FALSE} knitr::opts_chunk$set( collapse = TRUE, comment = "#>" ) ``` ## A Mini-Introduction to R Markdown Markdown documents are text files that contain a mixture of standard prose and programming code that can be easily be rendered as HTML or PDF outputs. During this rendering process, any code blocks are run and the results embedded in the output document. This can be really useful for making figures and tables to help describe a data set and to document analyses. [R markdown](https://rmarkdown.rstudio.com/) is a flavour of markdown that interfaces with the [R statistical platform](https://www.r-project.org/). Code can included in R markdown documents in 'chunks' such as the one shown below: ```{r setup, include=FALSE} # This is setup code that is not displayed in the rendered HTML file but includes packages # needed for producing the metadata document knitr::opts_chunk$set(echo = TRUE) # Import the Living Norway tools into R library(LivingNorwayR) ``` However, you will only see this code chunk in the original markdown text. At the top of the code chunk you will see the line `input=FALSE`. This means that the code is run but that neither the code itself or the results of the code is printed when rendering the document to HTML or any other output format. This is useful when you want to set up things in the background that you don't want rendered into the document. In this example the code chunk above calls the libraries that our markdown document will use so we don't need to have that code rendered to the HTML output. We can also make the code chunks print to the rendered document by removing the `include=FALSE` term. Sometimes, you might only want the result to be created in the rendered document. For example, when producing figures, we often do not want the code that produces the figure in the rendered document, just the figure itself. By setting `echo=FALSE` in the code chunk options then the code itself will not be rendered in the output document. For example the code chunk below will appear as code in the markdown document but will be replaced by a figure in the rendered document. ```{r figExample, echo=FALSE} plot(x = runif(100), y = runif(100), xlab = "x-axis", ylab = "y-axis") ``` The easiest way to render this document is to open it in [RStudio](https://www.rstudio.com/) and then click on the 'Knit' button that is in the top left-hand corner. A rendered version of the document is then opened in a browser. We can also call R functions 'inline'. For example in the markdown version of the document the term: `r 2 + 2` appears as 'r 2+2' but, in the rendered version, R is called and the calculation is performed. The statement is then replaced by the output (in this case '4'). A full introduction to R markdown is beyond the scope of this document but there are number of [great resources](https://bookdown.org/yihui/rmarkdown/) to learn more. When using markdown to describe the metadata of the project we can use a number of functions described in the Living Norway package to help flag sections of text that we want to export as information to appear in an EML file. The code chunk below will allow you to see flagged sections of text being rendered in a red colour in HTML output. For normal descriptions of metadata you would not want this so you should delete this code chunk for your own metadata descriptions. ```{css} span.LNmetadata { color: red; } ``` ## The Dataset Metadata must have a dataset tag. We give this tag an ID and it serves as a parent ID for a lot of other tags that describe the dataset. Often we don't want to print any text associated with this tag to the output so we can therefore set the `isHidden` argument to `TRUE` so that the tag is invisible in the rendered output. The main purpose of calling this function is to set an ID for the dataset tag that can be used to relate other things to it (here we have used the ID 'TOVEDataset'). In the dataset function we can also give information on the title to use in the dataset through the `title.tagText` argument. `r LNdataset("", tagID = "TOVEDataset", isHidden = TRUE, title.tagText = "TOV-E Bird monitoring sampling data")` We can also associate some keywords with the dataset. To do this we can set up a 'keywordSet' tag using the relevant tagging function `r LNkeywordSet("", tagID = "TOVEKeywordSet", parentID = "TOVEDataset", isHidden = TRUE)` and then specifying keywords such as `r LNkeyword("breeding birds", parentID = "TOVEKeywordSet")` and `r LNkeyword("sampling event", parentID = "TOVEKeywordSet")`. We must also specify some contact information for the individual or organisation responsible for coordinating with users of the dataset. Here the responsible user is `r LNcontact("", tagID = "TOVEContact", parentID = "TOVEDataset")` `r LNindividualName("", parentID = "TOVEContact", givenName.tagText = "John Atle", surName.tagText = "Kålås")`. ## Abstract We will need to produce an abstract for the data. You can flag the abstract for export to EML using the following inline code: `r LNabstract("Data from the project: \"Extensive monitoring of breeding birds (TOV-E)\" from 2006 up until today. The project is carried out in cooperation between NOF BirdLife Norway, Norwegian Institute for Nature Research (NINA) and Norwegian Environment Agency, and is the most important project for monitoring population trends for Norwegian bird species on land.", tagID = "TOVEAbstract", parentID = "TOVEDataset")` The Living Norway package will also allow for alternative translations of EML elements. In the inline code above we set the tagID argument. We can provide an alternative translation for the element with that tagID using the following code: `r LNaddTranslation("Data fra prosjektet \"Ekstensiv overvåking av hekkefugl (TOV-E)\" fra 2006 og frem til i dag. Prosjektet utføres i samarbeid mellom Norsk Ornitologisk Forening, Norsk Institutt for Naturforskning og Miljødirektoratet og er det viktigste prosjektet for å overvåke populasjonstrender for norske fuglearter på land.", lang = "nb", parentID = "TOVEAbstract")` By default, alternative translations are hidden in rendered HTML output. The information is still there but it is not displayed when being opened by a browser. This is useful when you want information to be exported to the EML file but do not to display them in the rendered HTML. If you would rather the alternative translation be displayed, then you can add the argument `isHidden=FALSE` to the `LNaddTranslation` function. ## Dataset creators The dataset was created by the following people: + `r LNcreator(tagText = "", tagID = "TOVECreator1", parentID = "TOVEDataset", individualName.tagText = "", individualName.givenName.tagText = "John Atle", individualName.surName.tagText = "Kålås")` who is a `r LNpositionName(parentID = "TOVECreator1", tagText = "senior researcher")` at the `r LNorganizationName(parentID = "TOVECreator1", tagText = "Norwegian Institute for Nature Research")` (`r LNelectronicMailAddress(parentID = "TOVECreator1", tagText = "john.kalas@nina.no")`). + `r LNcreator(tagText = "", tagID = "TOVECreator2", parentID = "TOVEDataset", individualName.tagText = "", individualName.givenName.tagText = "Ingar Jostein", individualName.surName.tagText = "Øien")` who is a `r LNpositionName(parentID = "TOVECreator2", tagText = "fagsjef")` at the `r LNorganizationName(parentID = "TOVECreator2", tagText = "Norsk Ornitologisk Forening")` (`r LNelectronicMailAddress(parentID = "TOVECreator2", tagText = "ingar@birdlife.no")`). + `r LNcreator(tagText = "", tagID = "TOVECreator3", parentID = "TOVEDataset", individualName.tagText = "", individualName.givenName.tagText = "Bård", individualName.surName.tagText = "Stokke")` who is a `r LNpositionName(parentID = "TOVECreator3", tagText = "senior researcher")` at the `r LNorganizationName(parentID = "TOVECreator3", tagText = "Norwegian Institute for Nature Research")` (`r LNelectronicMailAddress(parentID = "TOVECreator3", tagText = "bard.stokke@nina.no")`). + `r LNcreator(tagText = "", tagID = "TOVECreator4", parentID = "TOVEDataset", individualName.tagText = "", individualName.givenName.tagText = "Roald", individualName.surName.tagText = "Vang")` who is a `r LNpositionName(parentID = "TOVECreator4", tagText = "data manager")` at the `r LNorganizationName(parentID = "TOVECreator4", tagText = "Norwegian Institute for Nature Research")` (`r LNelectronicMailAddress(parentID = "TOVECreator4", tagText = "roald.vang@nina.no")`).