README.Rmd

---
title: "create a TS diagram as a ggplot"
author: "David Kaiser"
date: "2018/01/16"
output: github_document
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(echo = TRUE)
source("ggTS_DK.R")
```

### Description

A TS diagram, Temperature-Salinity-diagram, plots the **potential temperature** of water over **salinity**. Many water masses have characteristic shapes in a TS diagram, [which is used in physical oceanography to identify water masses and their mixing.](https://doi.org/10.1016/S0422-9894(08)71172-3)

This function requires the input of vectors of **potential temperature** and **salinity**. The *gws* package is used to calculate potential density for plotting of isopycnals (contours of the same density). This calculation requires a **reference pressure**, which defaults to 0, the sea surface.

A third vector can optionally be supplied to **col.par** to be plotted in color, and can be named with a string supplied to **col.name**.

Use [![DOI](https://zenodo.org/badge/112729228.svg)](https://zenodo.org/badge/latestdoi/112729228) to cite a permanent archived version of the function.


### Arguments

  *sal* -- vector of salinity values
  
  *pot.temp* -- vector of potential temperature values in degree C
  
  *reference.p = 0* -- reference pressure which was also used to calculate potential temperature
  
  *col.par = NA* -- optional vector of a parameter to be displayed as color of the TS-pairs
  
  *col.name = "col.par"* -- optional name of the "col.par" to be used on the color bar

### Plot

```{r example_data}
example <- read.csv("example_data/example_data.csv")

head(example)
```

The data will be plotted using the *ggplot2* package.

```{r plot_result, echo=TRUE, message=FALSE, warning=FALSE}
ggTS(sal = example$salinity, 
        pot.temp = example$potential.temperature, 
        reference.p = 0,
        col.par = example$depth, 
        col.name = "depth [m]")
```

**NOTE**: the special "Â" character does not show when the function is used in R, this seems to be a markdown/knitr problem

Since the result is a ggplot, it can be altered and amended:
```{r extend_plot, echo=TRUE, message=FALSE, warning=FALSE}
p1 <- ggTS(sal = example$salinity, 
        pot.temp = example$potential.temperature, 
        reference.p = 0,
        col.par = example$depth, 
        col.name = "depth [m]")
p1 + scale_color_gradient(low = "grey", high = "black", name = "something\nelse") +
      annotate(geom = "text", x = 15, y = 6, color = "red", size = 14, label = "ADD\nSTUFF")
```

Plot a TS diagram with isopycnals running more horizontally
```{r example_data1}
example1 <- read.csv("example_data/example_data1.csv")

head(example1)
```

```{r plot_result1, echo=TRUE, message=FALSE, warning=FALSE}
ggTS(sal = example1$salinity, 
        pot.temp = example1$potential.temperature, 
        reference.p = 0,
        col.par = example1$depth, 
        col.name = "depth [m]")
```