---
csl: template.csl
css: mystyle.css
output: 
  if (requireNamespace("BiocStyle", quietly = TRUE) & (Sys.info()[['sysname']] != "Windows")) {
    BiocStyle::html_document
  } else if (requireNamespace("rmarkdown", quietly = TRUE)) {
    rmarkdown::html_document
  } else html_document
vignette: |
  %\VignetteEngine{knitr::rmarkdown} 
  %\VignetteIndexEntry{openSkies} 
  \usepackage[utf8]{inputenc}
---



```{r setup, echo=FALSE}
knitr::opts_chunk$set(message=FALSE, fig.path='figures/', eval=FALSE)
```

<!-- Title block -->
<br>
<p style="text-align:center;font-size:200%;color:Red"> openSkies </p>
<p style="text-align:center;font-size:90%;color:Gray"> Rafael Ayala, 
Daniel Ayala, Aleix Sellés, Lara Sellés Vidal </p>
<p style="text-align:center;font-size:90%;color:Gray"> October 14, 2020 </p>
<br>

# Introduction

OpenSky (https://opensky-network.org/) provides free access to different types 
of flight and aircraft information. Flight information includes lists of 
aicrafts that landed at or departed from a specific airport and flights 
registered during a certain time interval. It is also possible to retrieve 
status informations received from aircraft transponders, including positional 
information, origin and destination.

openSkies provides an R interface to the OpenSky REST API, which aims to 
automate and facilitate the retrieval and utilization of the information 
provided by OpenSky.

# Installation instructions

Before installing <b>openSkies</b>, make sure you have the latest version of R
installed. To install <b>openSkies</b>, start R and enter: 

```{r tidy = TRUE, eval = FALSE}
install.packages("openSkies")
```

Once installed, the package can be loaded as shown below:

```{r tidy = TRUE, eval = TRUE}
library(openSkies)
```

# Accessing flight information

Information regarding flights can be accessed in four ways: by airport of
arrival, by airport of departure, by aircraft and by time interval. For the 
first two access modes, it is necessary to provide the ICAO code of the airport.
This can be obtained in websites such as https://www.world-airport-codes.com/.
Some examples are "EDDF" for Frankfurt International Airport (Germany), or 
"LEBL" for Barcelona Airport (Spain).

For retrieval of flights by aicraft, it is necessary to provide the ICAO 24-bit
address of the aircraft. This can be obtained from multiple sources, such as
http://www.airframes.org/. For example, 346190 corresponds to an ATR 72-600
of Air Nostrum with registration EC-NCD.

The function <b>getAirportArrivals()</b> lists all flights that arrived at a
given airport.

```{r tidy = TRUE}
# Get all flights that arrived at Frankfurt International Airport on the 29th of
# January, 2018 between 12 PM and 1 PM, local time.

getAirportArrivals(airport="EDDF", startTime="2018-01-29 12:00:00", 
                   endTime="2018-01-29 13:00:00", timeZone="Europe/Berlin")
```

The function <b>getAirportDepartures()</b> lists all flights that arrived at a
given airport.

```{r tidy = TRUE}
# Get all flights that departed from Barcelona Airport on the 12th of October,
# 2020 between 5 AM and 7 AM, local time.

getAirportDepartures(airport="LEBL", startTime="2020-10-12 05:00:00", 
                     endTime="2020-10-12 07:00:00", timeZone="Europe/Madrid")
```

The function <b>getAircraftFlights()</b> lists all flights performed by a given
aircraft.

```{r tidy = TRUE}
# Get all flights registered for the aircraft with ICAO 24-bit address 346190 
# during the 26th of July, 2019.

getAircraftFlights("346190", startTime="2019-07-26 00:00:00", 
                   endTime="2019-07-26 23:59:59", timeZone="Europe/Madrid")
```

The function <b>getIntervalFlights()</b> lists all flights registered during a 
given time interval, by any aircraft. It should be noted that such type of
requests will return a large number of results depending on the length of the
time interval.

```{r tidy = TRUE}
# Obtain a list with information for all the flights registered during the 16th
# of November, 2019 between 9 AM and 10 AM, London time.

flights <- getIntervalFlights(startTime="2019-11-16 09:00:00", 
                              endTime="2019-11-16 10:00:00", 
                              timeZone="Europe/London")

# Count the number of registered flights.

length(flights)
```

# Accessing aircraft state vectors

State vectors contain status information sent by the transponder of an aircraft.
This includes position, altitude, country of origin, speed, and other types of
data. While it is possible to perform these requests anonymously, authenticating
as a registered user offers access to additional data (see manual pages for
details).

It is possible to obtain a set of state vectors corresponding to information
received at a specified time point, filtered by different criteria (such as 
aircraft or location). 

```{r tidy = TRUE}
# Obtain a list with the state vectors for all aircrafts currently flying over
# an area covering Switzerland.

getSingleTimeStateVectors(minLatitude=45.8389, maxLatitude=47.8229, 
                          minLongitude=5.9962, maxLongitude=10.5226)

# Obtain the state vector for aircraft with ICAO 24-bit address 403003 for
# the 8th of October, 2020 at 16:50 London time.

getSingleTimeStateVectors(aircraft="403003", time="2020-10-08 16:50:00", 
                          timeZone="Europe/London")
```

It is also possible to retrieve a time series of state vectors for a specific
aircraft. It should be noted that this type of requests can take a relatively
long time to finish if a large amount of data points are requested.

```{r tidy = TRUE}
# Obtain a time series of state vectors for the aircraft with ICAO 24-bit 
# address 403003 for the 8th of October, 2020 between 16:50 and 16:53 (London
# time), with a time resolution of 1 minute.

getAircraftStateVectorsSeries("403003", startTime = "2020-10-08 16:50:00", 
                              endTime = "2020-10-08 16:52:00", 
                              timeZone="Europe/London", timeResolution=60)
```

# System of R6 classes for aviation data

openSkies also aims to establish standard data structures for the analysis of
aviation data. To that extent, a set of R6 classes is defined. The classes
defined so far include openSkiesAirport, openSkiesAircraft, openSkiesFlight,
openSkiesRoute, openSkiesStateVector and openSkiesStateVectorSet. For a 
detailed description of each class and their available methods, please check
the manual of the package.

# References

https://opensky-network.org/

https://www.world-airport-codes.com/

http://www.airframes.org/