# Processing METAR weather reports

# 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

    library(dplyr)
    #>
    #> Attaching package: 'dplyr'
    #> The following objects are masked from 'package:stats':
    #>
    #>     filter, lag
    #> The following objects are masked from 'package:base':
    #>
    #>     intersect, setdiff, setequal, union
    library(pmetar)
    metar_get("EPWA")
    #> Getting airport informaiton from the file downloaded from
    #> http://ourairports.com/data/airports.csv
    #> Getting information from Aviation Weather Center www.aviationweather.gov/metar
    #> Don't use for flight planning or navigation!
    #> [1] "EPWA 030830Z 15003KT 110V190 0500 R33/0600U FZFG VV002 M00/M00 Q1030 BECMG 0800 FG"

Now let’s take a look at Newark Liberty International Airport, EWR IATA code. This type of code you find on your airplane tickets.

    metar_get("EWR")
    #> Getting airport informaiton from the file downloaded from
    #> http://ourairports.com/data/airports.csv
    #> Getting information from Aviation Weather Center www.aviationweather.gov/metar
    #> Don't use for flight planning or navigation!
    #> [1] "KEWR 030751Z 23009KT 10SM FEW250 M02/M10 A3001 RMK AO2 SLP162 T10171100"

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/.

    dm <- metar_get_historical("JFK", start_date = "2020-06-25", end_date = "2020-06-29", from = "iastate")
    #> Getting airport informaiton from the file downloaded from
    #> http://ourairports.com/data/airports.csv
    #> Iowa Environmental Mesonet web page of Iowa State University
    #> ASOS-AWOS-METAR http://mesonet.agron.iastate.edu/AWOS/
    #> Don't use for flight planning or navigation!
    head(dm)
    #> [1] "202006250000 METAR KJFK 250000Z AUTO 27015KT 10SM CLR 28/12 A2978 RMK T02800120 MADISHF"
    #> [2] "202006250005 METAR KJFK 250005Z AUTO 26014KT 10SM CLR 28/11 A2978 RMK T02800110 MADISHF"
    #> [3] "202006250010 METAR KJFK 250010Z AUTO 27016KT 10SM CLR 28/12 A2979 RMK T02800120 MADISHF"
    #> [4] "202006250015 METAR KJFK 250015Z AUTO 26014KT 10SM CLR 27/12 A2979 RMK T02700120 MADISHF"
    #> [5] "202006250020 METAR KJFK 250020Z AUTO 27013KT 10SM CLR 27/12 A2979 RMK T02700120 MADISHF"
    #> [6] "202006250025 METAR KJFK 250025Z AUTO 27014KT 10SM CLR 27/12 A2979 RMK T02700120 MADISHF"

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.

    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

    (dm[length(dm)])
    #> [1] "202006292355 METAR KJFK 292355Z AUTO 07007KT 10SM FEW079 24/18 A2986 RMK T02400180  LTG DSNT S! MADISHF"
    my_report <- substr(dm[length(dm)], 14, nchar(dm[length(dm)]))
    my_report
    #> [1] "METAR KJFK 292355Z AUTO 07007KT 10SM FEW079 24/18 A2986 RMK T02400180  LTG DSNT S! MADISHF"

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

    metar_airport(my_report)
    #> [1] "KJFK"

and find the KJFK geographical coordinates, elevation, airport IATA code, airport name and source of information.

    metar_location(metar_airport(my_report))
    #> Getting airport informaiton from the file downloaded from
    #> https://ourairports.com/data/airports.csv
    #> created by David Megginson
    #> # A tibble: 1 x 7
    #>   ICAO_Code IATA_Code Airport_Name      Longitude Latitude Elevation Source
    #>   <chr>     <chr>     <chr>                 <dbl>    <dbl>     <dbl> <chr>
    #> 1 KJFK      JFK       John F Kennedy I…     -73.8     40.6      3.96 http://our…

### Day and time

The third element 282355Z includes a day of a month, a time and a time zone.

    metar_day(my_report)
    #> [1] 29
    metar_hour(my_report)
    #> [1] "23:55"
    metar_time_zone(my_report)
    #> [1] "Z"

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.

    metar_dir(my_report)
    #> [1] "70"
    metar_speed(my_report, metric = TRUE)
    #> [1] 3.601113
    metar_speed(my_report, metric = FALSE)
    #> [1] 7

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.

    variable_direction_METAR <- "EPWA 281830Z 18009KT 140V200 9999 SCT037 03/M01 Q1008 NOSIG"
    metar_dir(variable_direction_METAR)
    #> [1] "180, variable from 140 to 200"

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.

    metar_dir(variable_direction_METAR, numeric_only = TRUE)
    #> [1] 180

### 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.

    metar_visibility(my_report, metric = TRUE)
    #> [1] "16093.44"
    metar_visibility(my_report, metric = FALSE)
    #> [1] "10"

### Weather conditions

The function metar_wx_codes extracts and parses the below weather conditions codes:

    metarWXcodes
    #>             Type Abbreviation                                         Meaning
    #> 1     Descriptor           MI                         Shallow (French: Mince)
    #> 2     Descriptor           BC                         Patches (French: Bancs)
    #> 3     Descriptor           BL                                         Blowing
    #> 4     Descriptor           TS                                    Thunderstorm
    #> 5     Descriptor           PR                                         Partial
    #> 6     Descriptor           DR                                    Low drifting
    #> 7     Descriptor           SH                                         Showers
    #> 8     Descriptor           FZ                                        Freezing
    #> 9      Intensity            -                                 Light intensity
    #> 10     Intensity            +                                 Heavy intensity
    #> 11     Intensity        blank                              Moderate intensity
    #> 12     Intensity           VC                                 In the vicinity
    #> 13   Obscuration           FG                                             Fog
    #> 14   Obscuration           BR                            Mist (French: Brume)
    #> 15   Obscuration           DU                                 Widespread Dust
    #> 16   Obscuration           SA                                            Sand
    #> 17   Obscuration           VA                                    Volcanic Ash
    #> 18   Obscuration           HZ                                            Haze
    #> 19   Obscuration           FU                           Smoke (French: Fumee)
    #> 20   Obscuration           PY                                           Spray
    #> 21         Other           SQ                                          Squall
    #> 22         Other           DS                                       Duststorm
    #> 23         Other           FC                                    Funnel Cloud
    #> 24         Other           PO                             Dust or Sand Whirls
    #> 25         Other           SS                                       Sandstorm
    #> 26 Precipitation           RA                                            Rain
    #> 27 Precipitation           SN                                            Snow
    #> 28 Precipitation           IC                                    Ice Crystals
    #> 29 Precipitation           GR                            Hail (French: Grele)
    #> 30 Precipitation           UP                           Unknown Precipitation
    #> 31 Precipitation           DZ                                         Drizzle
    #> 32 Precipitation           SG                                     Snow Grains
    #> 33 Precipitation           PL                                     Ice Pellets
    #> 34 Precipitation           GS Small Hail and/or Snow Pellets (French: Gresil)
    #> 35 Precipitation
    #> 36          Time            B                                   Began At Time
    #> 37          Time     2 digits                         Minutes of current hour
    #> 38          Time            E                                   Ended At Time
    #> 39          Time     4 digits                          Hour/Minutes Zulu Time

In our METAR examples part -RA informs about weather conditions.

    metar_wx_codes(my_report)
    #> [1] ""

This part of a METAR can be quite complex, like in the below example:

    metar_wx_codes("202002022205 METAR KEWR 022205Z AUTO 24008KT 6SM -RA -SN BR SCT006 BKN014 OVC024 02/01 A2954 RMK T00200010 MADISHF")
    #> [1] "Light intensity: Rain; Light intensity: Snow; Mist (French: Brume)"

### Cloud coverage

Next part, SCT028 SCT035 BKN079, informs about a cloud coverage

    metar_cloud_coverage(my_report)
    #> [1] "Few (1-2 oktas) at 7900 ft (2407.92 m)"

### 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 T02300200.

    metar_temp(my_report)
    #> [1] 24

If there is a letter M in the front of two digits, M23/00, or there is a digit one after T, T1230, the temperature is below zero Celsius degrees.
The dew point can be decoded from the last two digits 23/20, or more detailed from T02300200. Dew points below zero Celsius degrees are decoded in the same method as above. For example 04/M03 or T00391033 mean that the dew point temperature is -3 Celsius degrees or more precisely -3.3 Celsius degrees.

    metar_dew_point(my_report)
    #> [1] 18

Here there is a report with the more precise temperature information in the RMK remarks part.

    metar_temp("202001010851 METAR KEWR 010851Z 27010KT 10SM FEW030 BKN070 BKN100 BKN210 04/M03 A2969 RMK SLP054 T00391033 52012")
    #> [1] 3.9
    metar_dew_point("202001010851 METAR KEWR 010851Z 27010KT 10SM FEW030 BKN070 BKN100 BKN210 04/M03 A2969 RMK SLP054 T00391033 52012")
    #> [1] -3.3

### 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.

    metar_pressure(my_report)
    #> [1] 1011.18

The pressure value can be also presented in a METAR report as Q1008, already in hPa.

    metar_pressure("EPWA 281830Z 18009KT 140V200 9999 SCT037 03/M01 Q1008 NOSIG")
    #> [1] 1008

If a pressure is needed in inHg (inch of mercury), the parameter altimeter has to be set to TRUE.

    metar_pressure("EPWA 281830Z 18009KT 140V200 9999 SCT037 03/M01 Q1008 NOSIG", altimeter = TRUE)
    #> [1] 29.77

### Wind shear

Information about wind shear can be extracted with the use of the function metar_windshear()

    metar_windshear("CYWG 172000Z 30015G25KT 3/4SM R36/4000FT/D -SN BLSN BKN008 OVC040 M05/M08 A2992 REFZRA WS RWY36 RMK SF5NS3 SLP134")
    #> [1] "Wind shear runway RWY36"

### Runway visibility

Information about runways visibility can be extracted with the use of the function metar_rwy_visibility(), in meters

    metar_rwy_visibility("CYWG 172000Z 30015G25KT 3/4SM R36/4000FT/D -SN BLSN BKN008 OVC040 M05/M08 A2992 REFZRA WS RWY36 RMK SF5NS3 SLP134")
    #> [1] "Runway visual range for runway R36 is 1219.2 meters with downward trend"

or in feet

    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)
    #> [1] "Runway visual range for runway R36 is 4000 ft with downward trend"

## 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.

    head(dm)
    #> [1] "202006250000 METAR KJFK 250000Z AUTO 27015KT 10SM CLR 28/12 A2978 RMK T02800120 MADISHF"
    #> [2] "202006250005 METAR KJFK 250005Z AUTO 26014KT 10SM CLR 28/11 A2978 RMK T02800110 MADISHF"
    #> [3] "202006250010 METAR KJFK 250010Z AUTO 27016KT 10SM CLR 28/12 A2979 RMK T02800120 MADISHF"
    #> [4] "202006250015 METAR KJFK 250015Z AUTO 26014KT 10SM CLR 27/12 A2979 RMK T02700120 MADISHF"
    #> [5] "202006250020 METAR KJFK 250020Z AUTO 27013KT 10SM CLR 27/12 A2979 RMK T02700120 MADISHF"
    #> [6] "202006250025 METAR KJFK 250025Z AUTO 27014KT 10SM CLR 27/12 A2979 RMK T02700120 MADISHF"

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).

    decoded_metars <- metar_decode(dm)
    #> Getting airport informaiton from the file downloaded from
    #> https://ourairports.com/data/airports.csv
    #> created by David Megginson

The following columns were created:

    names(decoded_metars)
    #>  [1] "Remark"              "Airport_ICAO"        "METAR_Date"
    #>  [4] "Day_of_Month"        "Hour"                "Time_zone"
    #>  [7] "Wind_speed"          "Wind_speed_unit"     "Gust"
    #> [10] "Gust_unit"           "Wind_shear"          "Wind_direction"
    #> [13] "Temperature"         "Dew_point"           "Pressure"
    #> [16] "Pressure_unit"       "Visibility"          "Visibility_unit"
    #> [19] "Cloud_coverage"      "Weather_information" "Runway_visibility"
    #> [22] "Airport_Name"        "Airport_IATA"        "Longitude"
    #> [25] "Latitude"            "Elevation"           "Decode_Date"
    #> [28] "Original_METAR"

First rows of the tibble with decoded METAR reports:

    print.data.frame(head(decoded_metars))
    #>                                         Remark Airport_ICAO          METAR_Date
    #> 1 Don't use for flight planning or navigation!         KJFK 2020-06-25 00:00:00
    #> 2 Don't use for flight planning or navigation!         KJFK 2020-06-25 00:05:00
    #> 3 Don't use for flight planning or navigation!         KJFK 2020-06-25 00:10:00
    #> 4 Don't use for flight planning or navigation!         KJFK 2020-06-25 00:15:00
    #> 5 Don't use for flight planning or navigation!         KJFK 2020-06-25 00:20:00
    #> 6 Don't use for flight planning or navigation!         KJFK 2020-06-25 00:25:00
    #>   Day_of_Month  Hour Time_zone Wind_speed Wind_speed_unit Gust Gust_unit
    #> 1           25 00:00         Z   7.716670             m/s   NA       m/s
    #> 2           25 00:05         Z   7.202226             m/s   NA       m/s
    #> 3           25 00:10         Z   8.231115             m/s   NA       m/s
    #> 4           25 00:15         Z   7.202226             m/s   NA       m/s
    #> 5           25 00:20         Z   6.687781             m/s   NA       m/s
    #> 6           25 00:25         Z   7.202226             m/s   NA       m/s
    #>   Wind_shear Wind_direction Temperature Dew_point Pressure Pressure_unit
    #> 1       <NA>            270          28        12  1008.47           hPa
    #> 2       <NA>            260          28        11  1008.47           hPa
    #> 3       <NA>            270          28        12  1008.81           hPa
    #> 4       <NA>            260          27        12  1008.81           hPa
    #> 5       <NA>            270          27        12  1008.81           hPa
    #> 6       <NA>            270          27        12  1008.81           hPa
    #>   Visibility Visibility_unit
    #> 1   16093.44               m
    #> 2   16093.44               m
    #> 3   16093.44               m
    #> 4   16093.44               m
    #> 5   16093.44               m
    #> 6   16093.44               m
    #>                                                               Cloud_coverage
    #> 1 No clouds below 12,000 ft (3,700 m) (U.S.) or 25,000 ft (7,600 m) (Canada)
    #> 2 No clouds below 12,000 ft (3,700 m) (U.S.) or 25,000 ft (7,600 m) (Canada)
    #> 3 No clouds below 12,000 ft (3,700 m) (U.S.) or 25,000 ft (7,600 m) (Canada)
    #> 4 No clouds below 12,000 ft (3,700 m) (U.S.) or 25,000 ft (7,600 m) (Canada)
    #> 5 No clouds below 12,000 ft (3,700 m) (U.S.) or 25,000 ft (7,600 m) (Canada)
    #> 6 No clouds below 12,000 ft (3,700 m) (U.S.) or 25,000 ft (7,600 m) (Canada)
    #>   Weather_information Runway_visibility                         Airport_Name
    #> 1                                       John F Kennedy International Airport
    #> 2                                       John F Kennedy International Airport
    #> 3                                       John F Kennedy International Airport
    #> 4                                       John F Kennedy International Airport
    #> 5                                       John F Kennedy International Airport
    #> 6                                       John F Kennedy International Airport
    #>   Airport_IATA Longitude Latitude Elevation         Decode_Date
    #> 1          JFK  -73.7789  40.6398    3.9624 2021-03-03 09:44:40
    #> 2          JFK  -73.7789  40.6398    3.9624 2021-03-03 09:44:40
    #> 3          JFK  -73.7789  40.6398    3.9624 2021-03-03 09:44:40
    #> 4          JFK  -73.7789  40.6398    3.9624 2021-03-03 09:44:40
    #> 5          JFK  -73.7789  40.6398    3.9624 2021-03-03 09:44:40
    #> 6          JFK  -73.7789  40.6398    3.9624 2021-03-03 09:44:40
    #>                                                                            Original_METAR
    #> 1 202006250000 METAR KJFK 250000Z AUTO 27015KT 10SM CLR 28/12 A2978 RMK T02800120 MADISHF
    #> 2 202006250005 METAR KJFK 250005Z AUTO 26014KT 10SM CLR 28/11 A2978 RMK T02800110 MADISHF
    #> 3 202006250010 METAR KJFK 250010Z AUTO 27016KT 10SM CLR 28/12 A2979 RMK T02800120 MADISHF
    #> 4 202006250015 METAR KJFK 250015Z AUTO 26014KT 10SM CLR 27/12 A2979 RMK T02700120 MADISHF
    #> 5 202006250020 METAR KJFK 250020Z AUTO 27013KT 10SM CLR 27/12 A2979 RMK T02700120 MADISHF
    #> 6 202006250025 METAR KJFK 250025Z AUTO 27014KT 10SM CLR 27/12 A2979 RMK T02700120 MADISHF