---
title: "Processing METAR weather reports"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{pmetar}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  tidy = FALSE
)
```

# Package pmetar

Pmetar is an R package that allows to download and parse current or historical METAR 
(Meteorological Terminal Aviation Routine Weather Report) reports,
mainly for airports.

**It has to be underlined that the package pmetar is not intended for flight planning or navigation.**

## Downloading a current METAR weather report
For downloading a METAR report we need to know an airport four letters ICAO code, 
International Civil Aviation Organization, or three letters IATA code,
International Air Transport Association.  
Let's download a current METAR weather report for Warsaw Okecie Airport. 
Its ICAO, International Civil Aviation Organization, code is EPWA. 
A report can be got from Aviation Weather Center <https://www.aviationweather.gov/metar>
```{r get a METAR report with ICAO code}
library(dplyr)
library(pmetar)
metar_get("EPWA")
```
Now let's take a look at Newark Liberty International Airport, EWR IATA code. 
This type of code you find on your airplane tickets.
```{r get a METAR report with IATA code}
metar_get("EWR")
```
The above message is intended for professionals like pilots or air traffic controllers. 
The first purpose of preparing the pmetar package was the need of extracting wind speed
and air pressure values from METAR reports for some airports in Poland. 
Later the package functionality was extended. We will go through
the main functions with a historical METAR report 
from John F. Kennedy International Airport.

## Downloading historical METAR weather report
The function metar_get_historical allows to download METAR weather reports for a defined period of time.
The default online source of METAR reports, *from = "iastate"* is the Iowa Environmental Mesonet
web page of Iowa State University ASOS-AWOS-METAR <http://mesonet.agron.iastate.edu/AWOS/>.    
```{r}
dm <- metar_get_historical("JFK", start_date = "2020-06-25", end_date = "2020-06-29", from = "iastate")
head(dm)
```
The second backup source, *from = "ogimet"* is Weather Information Service provided
by Ogimet <http://www.ogimet.com/>. Please take into consideration that Ogimet usually 
blocks too frequent requests for data due to the server overload, 
the requested period is limited to 31 days and for the most of airports
METAR reports are available from the beginning of the year 2005.
```{r, eval = FALSE}
metar_get_historical("JFK", start_date = "2020-06-25", end_date = "2020-06-29", from = "ogimet")
```
We will parse the last report from the above *dm*. In historical reports dates
and hours are placed at the beginning of texts. Normally it's extracted and parsed,
but for now let's remove it
```{r}
(dm[length(dm)])
my_report <- substr(dm[length(dm)], 14, nchar(dm[length(dm)]))
my_report
```
It has to be noted that the report part after the RMK, remarks, is not analyzed, 
except the temperature information, which is provide more precisely in remarks.

## Decoding main informatin from a single METAR weather report

The first element **METAR** indicates the text consist of a METAR weather report. 
If a report was issued under special circumstances, 
a text SPECI replaces METAR.

### Airport 
The second four letters element, **KJFK** identifies an airport from which a METAR issued. We can extract it 
```{r}
metar_airport(my_report)
```
and find the **KJFK** geographical coordinates, elevation, airport IATA code, airport name and source of information.
```{r}
metar_location(metar_airport(my_report))
```

### Day and time
The third element **282355Z** includes a day of a month, a time and a time zone.
```{r}
metar_day(my_report)
metar_hour(my_report)
metar_time_zone(my_report)
```
The fourth element, in our case **AUTO** informs that a report was generated automatically. 
If a report was manually corrected it is **COR**. This element is not taken into
consideration by the package pmetar.

### Wind speed and wind direction
Next, there is the text **07007KT** where three first digits informs about a wind direction
in degrees. Two next digits are a wind speed and the letters the end define units, here KT, 
hence a wind speed is in knots.
```{r}
metar_dir(my_report)
metar_speed(my_report, metric = TRUE)
metar_speed(my_report, metric = FALSE)
```
The function metar_speed reports a wind speed in m/s with the default value of
the parameter *metric = TRUE*, or in knots when *metric = FALSE*.  
When a wind direction varies, a METAR report has additional component, like **140V200**,
which informs that a wind direction fluctuates from 140 to 200 degrees.
```{r}
variable_direction_METAR <- "EPWA 281830Z 18009KT 140V200 9999 SCT037 03/M01 Q1008 NOSIG"
metar_dir(variable_direction_METAR)
```
In this case an output is character what can be useless for statistical calculations.
If only main direction in the numeric format is needed, 
it is possible to set the parameter *numeric_only = TRUE*.
```{r}
metar_dir(variable_direction_METAR, numeric_only = TRUE)
```

### Visibility
The part **10SM** is the visibility. In this case it's 10 statue miles. 
With  the default value of the paremeter *metric= TRUE* we get output in meters.
For *metric = FALSE* in statute miles. 
```{r}
metar_visibility(my_report, metric = TRUE)
metar_visibility(my_report, metric = FALSE)
```

### Weather conditions
The function metar_wx_codes extracts and parses the below weather conditions codes:
```{r}
metarWXcodes
```
In our METAR examples part **-RA** informs about weather conditions.
```{r}
metar_wx_codes(my_report)
```
This part of a METAR can be quite complex, like in the below example:
```{r}
metar_wx_codes("202002022205 METAR KEWR 022205Z AUTO 24008KT 6SM -RA -SN BR SCT006 BKN014 OVC024 02/01 A2954 RMK T00200010 MADISHF")
```

### Cloud coverage
Next part, **SCT028 SCT035 BKN079**, informs about a cloud coverage
```{r}
metar_cloud_coverage(my_report)
```

### Temperature and dew point
The temperature and the dew point can be extracted from two elements of a METAR report,
before the RMK remarks marker *23/20* which can be found in the most reports. 
Or from the part after the RMK remarks marker *T02300200*, more precise but not
always available.  
The temperature is coded in Celsius degrees, here **23**/20, or more detailed in T0**230**0200.
```{r}
metar_temp(my_report)
```
If there is a letter M in the front of two digits, **M**23/00, or there is a digit one after T,
T**1**230, the temperature is below zero Celsius degrees.  
The dew point can be decoded from the last two digits 23/**20**, or more detailed from T02300**200**. 
Dew points below zero Celsius degrees are decoded in the same method as above. For example 04/**M**03
or T0039**1**033 mean that the dew point temperature is -3 Celsius degrees or more
precisely -3.3 Celsius degrees.
```{r}
metar_dew_point(my_report)
```
Here there is a report with the more precise temperature information in the RMK remarks part.
```{r}
metar_temp("202001010851 METAR KEWR 010851Z 27010KT 10SM FEW030 BKN070 BKN100 BKN210 04/M03 A2969 RMK SLP054 T00391033 52012")
metar_dew_point("202001010851 METAR KEWR 010851Z 27010KT 10SM FEW030 BKN070 BKN100 BKN210 04/M03 A2969 RMK SLP054 T00391033 52012")
```

### Pressure
In our example a pressure value is coded in the  **A2972** as inHg (inch of mercury).
With the default parameter *altimeter = FALSE*, the function metar_pressure returns 
a pressure in hPa.
```{r}
metar_pressure(my_report)
```
The pressure value can be also presented in a METAR report as **Q1008**, already in hPa.
```{r}
metar_pressure("EPWA 281830Z 18009KT 140V200 9999 SCT037 03/M01 Q1008 NOSIG")
```
If a pressure is needed in inHg (inch of mercury), the parameter *altimeter*
has to be set to TRUE.
```{r}
metar_pressure("EPWA 281830Z 18009KT 140V200 9999 SCT037 03/M01 Q1008 NOSIG", altimeter = TRUE)
```

### Wind shear
Information about wind shear can be extracted with the use of the function metar_windshear()
```{r}
metar_windshear("CYWG 172000Z 30015G25KT 3/4SM R36/4000FT/D -SN BLSN BKN008 OVC040 M05/M08 A2992 REFZRA WS RWY36 RMK SF5NS3 SLP134")
```

### Runway visibility
Information about runways visibility can be extracted with the use of the function metar_rwy_visibility(), in meters
```{r}
metar_rwy_visibility("CYWG 172000Z 30015G25KT 3/4SM R36/4000FT/D -SN BLSN BKN008 OVC040 M05/M08 A2992 REFZRA WS RWY36 RMK SF5NS3 SLP134")
```
or in feet
```{r}
metar_rwy_visibility("CYWG 172000Z 30015G25KT 3/4SM R36/4000FT/D -SN BLSN BKN008 OVC040 M05/M08 A2992 REFZRA WS RWY36 RMK SF5NS3 SLP134",
                     metric = FALSE)
```

## Putting all together

### Decoding METAR reports 
Let's come back to our dm list with historical METAR reports downloaded at the top of this document.
Please notice that in all rows there are dates and hours in the front of METAR reports. It will be parsed
and placed in the column *METAR_Date* below.
```{r}
head(dm)
```
Now we can decode all elements and place them in the tibble. It is possible to choose between Metric (the default metric = TRUE) or Imperial (metric = FALSE) systems.
Pressure valuesc can be decoded in hPa (the default altimeter = FALSE) or in mmHg (altimeter = TRUE).
```{r}
decoded_metars <- metar_decode(dm)
```
The following columns were created:
```{r}
names(decoded_metars)
```
First rows of the tibble with decoded METAR reports:
```{r}
print.data.frame(head(decoded_metars))
```
