# Usage

The {RClimacell} package provides four high-level wrapper functions to retrieve the Core layer data fields from the Climacell API version 4 using the Timeline Interface:

- `climacell_temperature`: obtains temperature related variables
- `climacell_wind`: obtains wind related variables
- `climacell_precip`: obtains precipitation related variables
- `climacell_celestial`: obtains the sunrise time, sunset time, and the moon phase
- `climacell_core`: obtains all of the data fields from the Core data layer using the Timeline interface

## Arguments

All of the high level wrapper functions consist of the following 5 arguments:

- `api_key`
- `lat`
- `long`
- `timestep`
- `start_time`
- `end_time`

### API Key

A valid API key from Climacell is required to use any of the functions within this package. Obtaining an API key is free and is limited to 1000 calls per day when using the CORE layers. By default, the functions will try to find an environment variable (within the .Renviron file) called “CLIMACELL_API”. If found, it will automatically use it. If you have a different environment variable name for the API key, you will need to explicity retrieve the environment variable and may not omit it from the function call.

### Latitude & Longitude

The latitude and longitude values are required and the functions will not work without them. Both of these values must be decimal values and cannot be in degrees, minutes, seconds, UTM, etc.

### Timestep

This argument identifies what interval the data must be in. For instance, if you are looking for daily data, then you’ll want to set the timestep to ‘1d’. This field is limited to the following values only:

Timestep | Interval | Lower Limit | Upper Limit
--- | --- | --- | ---
1m | 1 minute (per minute) | 6 hours prior to actual current UTC time | 6 hours ahead of actual current UTC time
15m | 15 minutes | 6 hours prior to actual current UTC time | 6 hours ahead of actual current UTC time
30m | 30 minutes | 6 hours prior to actual current UTC time | 6 hours ahead of actual current UTC time
1h | 1 hour (hourly) | 6 hours prior to actual current UTC time | 108 hours ahead of actual current UTC time
1d | 1 day (daily) | actual current UTC time | 15 days ahead of actual current UTC time
current | n/a | actual current UTC time | actual current UTC time

If a timestep of ‘current’ is used, then the start and end times will not be used.

This field must be identified correctly or the functions will not work. The only exception is the `climacell_celestial()` function since it can ONLY use a timestep of ‘1d’ (per the requirements of the API).

### Start & End Times

The start and end times help define the constraints around the data retrieval from the API. The start time is required; however, if it is missing, the functions will automatically use the current system time. If the system time is not reflective of the actual time, then the functions may not work as expected.

The end time is optional due to the error handling built in to the functions. Typically, omitting the end time value will yield a warning (which can be safely ignored) and the function will create an end time (internally) that will return the maximum results based on the timestep value chosen.

## Usage

Detailed information on any of the variables returned by the functions can be found on the CORE Layers page.

### Temperature

The `climacell_temperature()` function returns the following variables:

- `start_time`: the time of the reading. This value increments based on the timestep interval chosen (UTC).
- `temp_c`: the temperature at the time of reading (degrees Celsius).
- `temp_feel_c`: what the temperature actually feels like (degrees Celsius).
- `dewpoint`: the dewpoint at the time of the reading (degrees Celsius).
- `humidity`: the humidity at the time of the reading (%).

    library(dplyr)
    library(RClimacell)

    temperature_1m <- RClimacell::climacell_temperature(
                                            api_key = Sys.getenv('CLIMACELL_API'),
                                            timestep = '1m',
                                            lat = 41.878876,
                                            long = -87.635918,
                                            start_time = Sys.time() - lubridate::hours(5),
                                            end_time = NULL)
    dplyr::glimpse(temperature_1m)

    #> Rows: 661
    #> Columns: 5
    #> $ start_time  <dttm> 2021-03-22 15:20:00, 2021-03-22 15:21:00, 2021-03-22 15:2…
    #> $ temp_c      <dbl> 14.44, 14.44, 14.44, 14.44, 14.44, 14.44, 14.55, 14.66, 14…
    #> $ temp_feel_c <dbl> 12.63, 12.62, 12.62, 12.62, 12.62, 12.63, 12.66, 12.70, 12…
    #> $ dewpoint    <dbl> 1.60, 1.53, 1.46, 1.39, 1.32, 1.26, 1.36, 1.46, 1.56, 1.66…
    #> $ humidity    <dbl> 42.00, 41.80, 41.60, 41.40, 41.20, 41.00, 41.00, 41.00, 41…

### Precipitation

The `climacell_precip()` function returns the following variables:

- `start_time`: the time of the reading. This value increments based on the timestep interval chosen (UTC).
- `precipitation_intensity`: amount of precipitation that falls over time, covering the ground in a period of time (mm/hr).
- `precipitation_probability`: chance of precipitation that at least some minimum quantity of precipitation will occur within a specified forecast period and location (%).
- `precipitation_type_code`: types of precipitation often include the character or phase of the precipitation which is falling to ground level (code number returned by API).
- `precipitation_type_desc`: long description of the precipitation_type_code.
- `visibility`: measure of the distance at which an object or light can be clearly discerned (km).
- `pressure_surface_level`: force exerted against a surface by the weight of the air above the surface (at the surface level) (hPa).
- `pressure_sea_level`: force exerted against a surface by the weight of the air above the surface (at the mean sea level) (hPA).
- `cloud_cover`: fraction of the sky obscured by clouds when observed from a particular location (%)
- `cloud_base`: lowest altitude of the visible portion of a cloud (above ground level) (km)
- `cloud_ceiling`: highest altitude of the visible portion of a cloud (above ground level) (km)
- `solar_ghi`: amount of shortwave radiation received from above by a surface horizontal to the ground (W/m^2)
- `weather_code`: code number that conveys the most prominent weather condition (code number returned by API)
- `weather_desc`: long description of the weather_code

Depending on the actual weather forecasts and conditions, not all of the variables will have values. If any column has an NA value, it simply means that the API did not return a value for that specific variable for that specific start time.

    library(dplyr)
    library(RClimacell)

    precip_1h <- RClimacell::climacell_precip(
                                            api_key = Sys.getenv('CLIMACELL_API'),
                                            timestep = '1h',
                                            lat = 41.878876,
                                            long = -87.635918,
                                            start_time = Sys.time() - lubridate::hours(5),
                                            end_time = NULL)
    dplyr::glimpse(precip_1h)

    #> Rows: 113
    #> Columns: 14
    #> $ start_time                <dttm> 2021-03-22 15:20:00, 2021-03-22 16:20:00, 2…
    #> $ precipitation_intensity   <dbl> 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,…
    #> $ precipitation_probability <dbl> 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0,…
    #> $ precipitation_type_code   <dbl> 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1,…
    #> $ precipitation_type_desc   <chr> "Rain", "Rain", "Rain", "Rain", "Rain", "Rai…
    #> $ visibility                <dbl> 10, 10, 10, 10, 10, 10, 16, 16, 16, 16, 16, …
    #> $ pressure_surface_level    <dbl> 1000.86, 999.67, 999.29, 998.89, 998.39, 998…
    #> $ pressure_sea_level        <dbl> 1018.22, 1018.07, 1016.67, 1016.24, 1015.52,…
    #> $ cloud_cover               <dbl> 33.31, 33.31, 83.31, 33.31, 66.69, 0.00, 7.8…
    #> $ cloud_base                <dbl> NA, NA, NA, NA, NA, NA, NA, NA, 1.57, 1.06, …
    #> $ cloud_ceiling             <dbl> NA, NA, NA, NA, NA, NA, NA, NA, 9.59, 9.22, …
    #> $ solar_ghi                 <dbl> 354.13, 453.50, 126.88, 526.69, 252.81, 632.…
    #> $ weather_code              <dbl> 1100, 1100, 1001, 1100, 1102, 1000, 1000, 11…
    #> $ weather_desc              <chr> "Mostly Clear", "Mostly Clear", "Cloudy", "M…

### Wind

The `climacell_wind()` function returns the following variables:

- `start_time`: the time of the reading. This value increments based on the timestep interval chosen (UTC).
- `wind_speed`: atmospheric quantity caused by air moving from high to low pressure, usually due to changes in temperature (at 10m) (m/s).
- `wind_gust`: maximum brief increase in the speed of the wind, usually less than 20 seconds (at 10m) (m/s).
- `wind_direction`: direction from which it originates, measured in degrees clockwise from due north (at 10m) (degrees)

Depending on the actual weather forecasts and conditions, not all of the variables will have values. If any column has an NA value, it simply means that the API did not return a value for that specific variable for that specific start time.

    library(dplyr)
    library(RClimacell)

    wind_1m <- RClimacell::climacell_wind(
                                            api_key = Sys.getenv('CLIMACELL_API'),
                                            timestep = '1m',
                                            lat = 41.878876,
                                            long = -87.635918,
                                            start_time = Sys.time() - lubridate::hours(5),
                                            end_time = NULL)

    dplyr::glimpse(wind_1m)

    #> Rows: 661
    #> Columns: 4
    #> $ start_time     <dttm> 2021-03-22 15:20:00, 2021-03-22 15:21:00, 2021-03-22 1…
    #> $ wind_speed     <dbl> 0.89, 0.98, 1.07, 1.16, 1.25, 1.34, 1.29, 1.25, 1.20, 1…
    #> $ wind_gust      <dbl> 3.13, 3.03, 2.94, 2.85, 2.76, 2.68, 2.72, 2.76, 2.81, 2…
    #> $ wind_direction <dbl> 246, 246, 246, 250, 250, 250, 250, 250, 250, 250, 214, …

### Celestial

The `climacell_celestial()` function returns the following variables:

- start_time: the time of the reading. This value increments based on the timestep interval chosen (UTC).
- sunrise_time: appearance of the Sun on the horizon due to Earth’s rotation (UTC).
- sunset_time: disappearance of the Sun below the horizon due to Earth’s rotation (UTC).
- moon_phase_code: shape of the directly sunlit portion of the Moon as viewed from Earth.
- moon_phase_description: long description of the moon_phase_code.

Note that the `timestep` value for this function can only be ‘1d’.

    library(dplyr)
    library(RClimacell)

    celestial_1d <- RClimacell::climacell_celestial(
                                            api_key = Sys.getenv('CLIMACELL_API'),
                                            timestep = '1d',
                                            lat = 41.878876,
                                            long = -87.635918,
                                            start_time = Sys.time(),
                                            end_time = NULL)

    dplyr::glimpse(celestial_1d)

    #> Rows: 15
    #> Columns: 5
    #> $ start_time             <dttm> 2021-03-22 11:00:00, 2021-03-23 11:00:00, 2021…
    #> $ sunrise_time           <dttm> 2021-03-22 11:50:00, 2021-03-23 11:48:20, 2021…
    #> $ sunset_time            <dttm> 2021-03-23 00:05:00, 2021-03-24 00:06:40, 2021…
    #> $ moon_phase_code        <int> 2, 2, 2, 2, 3, 4, 4, 4, 5, 5, 5, 6, 6, 6, 6
    #> $ moon_phase_description <chr> "First Quarter", "First Quarter", "First Quarte…

### Core

The `climacell_core()` function returns all of the variables in the aforementioned function calls. Note that the `timestep` must be equal to ‘1d’ if any of the celestial fields (e.g., moon phase, sunrise time, sunset time) are desired.

    library(dplyr)
    library(RClimacell)

    core_1m <- RClimacell::climacell_core(
                                            api_key = Sys.getenv('CLIMACELL_API'),
                                            timestep = '1d',
                                            lat = 41.878876,
                                            long = -87.635918,
                                            start_time = Sys.time(),
                                            end_time = NULL)

    dplyr::glimpse(core_1m)

    #> Rows: 661
    #> Columns: 21
    #> $ start_time                <dttm> 2021-03-22 15:20:00, 2021-03-22 15:21:00, 2…
    #> $ temp_c                    <dbl> 14.44, 14.44, 14.44, 14.44, 14.44, 14.44, 14…
    #> $ temp_feel_c               <dbl> 12.63, 12.62, 12.62, 12.62, 12.62, 12.63, 12…
    #> $ weather_code              <dbl> 1100, 1100, 1100, 1100, 1100, 1100, 1100, 11…
    #> $ weather_desc              <chr> "Mostly Clear", "Mostly Clear", "Mostly Clea…
    #> $ dewpoint                  <dbl> 1.60, 1.53, 1.46, 1.39, 1.32, 1.26, 1.36, 1.…
    #> $ humidity                  <dbl> 42.00, 41.80, 41.60, 41.40, 41.20, 41.00, 41…
    #> $ wind_speed                <dbl> 0.89, 0.98, 1.07, 1.16, 1.25, 1.34, 1.29, 1.…
    #> $ wind_direction            <dbl> 246, 246, 246, 250, 250, 250, 250, 250, NA, …
    #> $ wind_gust                 <dbl> 3.13, 3.03, 2.94, 2.85, 2.76, 2.68, 2.72, 2.…
    #> $ solar_ghi                 <dbl> 354.13, 354.12, 354.12, 354.12, 354.12, 354.…
    #> $ precipitation_type_code   <dbl> 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1,…
    #> $ precipitation_type_desc   <chr> "Rain", "Rain", "Rain", "Rain", "Rain", "Rai…
    #> $ precipitation_probability <dbl> 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,…
    #> $ precipitation_intensity   <dbl> 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,…
    #> $ cloud_cover               <dbl> 33.31, 33.31, 33.31, 33.31, 33.31, 33.31, 33…
    #> $ cloud_base                <dbl> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, …
    #> $ cloud_ceiling             <dbl> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, …
    #> $ visibility                <dbl> 10, 10, 10, 10, 10, 10, 10, 10, 10, 10, 10, …
    #> $ pressure_surface_level    <dbl> 1000.86, 1000.83, 1000.81, 1000.78, 1000.76,…
    #> $ pressure_sea_level        <dbl> 1018.22, 1018.21, 1018.21, 1018.21, 1018.21,…

Using a `timestep` of ‘1d’ results in the following:

    #> Rows: 15
    #> Columns: 25
    #> $ start_time                <dttm> 2021-03-22 11:00:00, 2021-03-23 11:00:00, 2…
    #> $ temp_c                    <dbl> 18.72, 12.37, 14.18, 7.26, 2.57, 4.03, 3.46,…
    #> $ temp_feel_c               <dbl> 18.72, 12.37, 14.18, 7.26, -0.81, 1.18, -0.5…
    #> $ weather_code              <dbl> 1102, 4200, 4000, 5001, 5001, 5100, 5001, 40…
    #> $ weather_desc              <chr> "Mostly Cloudy", "Light Rain", "Drizzle", "F…
    #> $ dewpoint                  <dbl> 5.20, 10.49, 10.07, 4.94, -1.81, 3.36, 2.56,…
    #> $ humidity                  <dbl> 62.11, 96.98, 97.27, 92.32, 74.93, 94.92, 94…
    #> $ wind_speed                <dbl> 6.46, 9.77, 10.72, 9.75, 7.94, 6.92, 9.87, 1…
    #> $ wind_direction            <dbl> 192.44, 143.24, 224.78, 61.08, 148.06, 71.76…
    #> $ wind_gust                 <dbl> 8.74, 13.92, 15.36, 12.24, 9.84, 10.74, 12.8…
    #> $ solar_ghi                 <dbl> 527.65, 459.38, 552.39, 557.51, 651.40, 137.…
    #> $ precipitation_type_code   <dbl> 1, 1, 1, 2, 2, 2, 2, 2, 2, 2, 1, 1, 2, 2, 2
    #> $ precipitation_type_desc   <chr> "Rain", "Rain", "Rain", "Snow", "Snow", "Sno…
    #> $ precipitation_probability <dbl> 0, 75, 25, 55, 20, 35, 30, 0, 5, 5, 55, 55, …
    #> $ precipitation_intensity   <dbl> 0.0000, 2.7397, 0.3605, 0.4792, 0.0222, 0.57…
    #> $ cloud_cover               <dbl> 100.00, 100.00, 100.00, 100.00, 100.00, 100.…
    #> $ cloud_base                <dbl> 7.92, 2.35, 5.70, 5.86, 1.09, 2.18, 0.91, 4.…
    #> $ cloud_ceiling             <dbl> 9.59, 8.88, 7.31, 8.26, 1.26, 3.35, 2.21, 2.…
    #> $ visibility                <dbl> 16.00, 16.00, 16.00, 24.14, 24.14, 24.14, 24…
    #> $ pressure_surface_level    <dbl> 1001.39, 996.92, 990.88, 992.93, 1001.49, 99…
    #> $ pressure_sea_level        <dbl> 1014.64, 1003.36, 1003.40, 1011.24, 1015.15,…
    #> $ sunrise_time              <dttm> 2021-03-22 11:50:00, 2021-03-23 11:48:20, 20…
    #> $ sunset_time               <dttm> 2021-03-23 00:05:00, 2021-03-24 00:06:40, 2…
    #> $ moon_phase_code           <dbl> 2, 2, 2, 2, 3, 4, 4, 4, 5, 5, 5, 6, 6, 6, 6
    #> $ moon_phase_description    <chr> "First Quarter", "First Quarter", "First Qu…