---
title: "Get started with climaemet 1.0.0"
author: <a href="https://orcid.org/0000-0001-8457-4658">Diego Hernangómez <img alt="ORCID logo" src="https://info.orcid.org/wp-content/uploads/2019/11/orcid_24x24.png" width="16" height="16" /></a>
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Get started with climaemet 1.0.0}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

<!-- climaemet.Rmd is generated from climaemet.Rmd.orig. Please edit that file -->




Since the last release, this package has been integrated into
[rOpenSpain](https://ropenspain.es/), a community of **R** enthusiasts whose
ultimate goal is to create high-quality **R** packages for data mining public
Spanish open sources.

From version **1.0.0** onward, we have introduced some improvements and
(breaking) changes on the package, in order to provide a smoother interaction
with the AEMET API service.

## API Key

### Get your API Key

To be able to download data from AEMET you will need a free API key which you
can get at <https://opendata.aemet.es/centrodedescargas/obtencionAPIKey>

Once that you have your API Key, you can use any of the following methods:

#### a. Set API Key with `aemet_api_key()`

This is the recommended option. Just type:


```r
aemet_api_key("YOUR_API_KEY", install = TRUE)
```

Using `install = TRUE` ensures that the API key is stored on your local computer
and it would be reloaded every time you load the library. From now on you can
forget about API keys!

#### b. Use an environment variable

This is a temporary alternative. You can set your API key as an environment
variable


```r
Sys.setenv(AEMET_API_KEY = "YOUR_API_KEY")
```

Note that this is only valid for the current session. You would need to re-run
this command each time you restart your session.

#### c. Modify your `.Renviron` file

This stores your API key permanently on your machine. You can start editing your
`.Renviron` running this command:

``` r
usethis::edit_r_environ()
```

Now you can add the following line to you `.Renviron` file:

    AEMET_API_KEY = YOUR_API_KEY

## New features

### `tidyverse` format

From **v1.0.0** onward, **climaemet** provides its results in [tibble
format](https://tibble.tidyverse.org/). Also, the functions try to guess the
correct format of the fields (i.e. something as a Date/Hour now is an hour,
numbers are parsed as double, etc.).

See how a tibble is displayed:


```r
# See a tibble in action

aemet_last_obs("9434")
#> # A tibble: 24 × 25
#>    idema   lon fint                 prec   alt  vmax    vv    dv   lat  dmax ubi       
#>    <chr> <dbl> <dttm>              <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> <chr>     
#>  1 9434  -1.00 2024-01-29 22:00:00     0   249   1.2   0.9   186  41.7   190 ZARAGOZA …
#>  2 9434  -1.00 2024-01-29 23:00:00     0   249   2     0.6   209  41.7   248 ZARAGOZA …
#>  3 9434  -1.00 2024-01-30 00:00:00     0   249   1.5   1.2   189  41.7   183 ZARAGOZA …
#>  4 9434  -1.00 2024-01-30 01:00:00     0   249   1.6   0.6   165  41.7   195 ZARAGOZA …
#>  5 9434  -1.00 2024-01-30 02:00:00     0   249   1.2   0.8   313  41.7   178 ZARAGOZA …
#>  6 9434  -1.00 2024-01-30 03:00:00     0   249   1.5   1     281  41.7   275 ZARAGOZA …
#>  7 9434  -1.00 2024-01-30 04:00:00     0   249   2.4   1.1   321  41.7   253 ZARAGOZA …
#>  8 9434  -1.00 2024-01-30 05:00:00     0   249   1.2   0.7   238  41.7   323 ZARAGOZA …
#>  9 9434  -1.00 2024-01-30 06:00:00     0   249   1.5   0.9   195  41.7   218 ZARAGOZA …
#> 10 9434  -1.00 2024-01-30 07:00:00     0   249   1.4   0.8   281  41.7   198 ZARAGOZA …
#> # ℹ 14 more rows
#> # ℹ 14 more variables: pres <dbl>, hr <dbl>, stdvv <dbl>, ts <dbl>, pres_nmar <dbl>,
#> #   tamin <dbl>, ta <dbl>, tamax <dbl>, tpr <dbl>, stddv <dbl>, inso <dbl>,
#> #   tss5cm <dbl>, pacutp <dbl>, tss20cm <dbl>
```

Note that when possible, data representing dates and numbers are converted to
the right format.

### Spatial objects: `sf`

Another major change in **v1.0.0** is the ability of return information on
spatial `sf` format, using `return_sf = TRUE`. The coordinate reference system
(CRS) used is **EPSG 4326**, that correspond to the **World Geodetic System
(WGS)** and return coordinates in latitude/longitude (unprojected coordinates):


```r
# You would need to install `sf` if not installed yet
# run install.packages("sf") for installation

library(ggplot2)
library(dplyr)

all_stations <- aemet_daily_clim(
  start = "2021-01-08", end = "2021-01-08",
  return_sf = TRUE
)


ggplot(all_stations) +
  geom_sf(aes(colour = tmed), shape = 19, size = 2, alpha = 0.95) +
  labs(
    title = "Average temperature in Spain",
    subtitle = "8 Jan 2021",
    color = "Max temp.\n(celsius)",
    caption = "Source: AEMET"
  ) +
  scale_colour_gradientn(
    colours = hcl.colors(10, "RdBu", rev = TRUE),
    breaks = c(-10, -5, 0, 5, 10, 15, 20),
    guide = "legend"
  ) +
  theme_bw() +
  theme(
    panel.border = element_blank(),
    plot.title = element_text(face = "bold"),
    plot.subtitle = element_text(face = "italic")
  )
```

<div class="figure">
<img src="./spatial-1.png" alt="Example: Temperature in Spain" width="100%" />
<p class="caption">Example: Temperature in Spain</p>
</div>


## Further enhancements

Other enhancements included on the **v1.0.0**:

-   All the functions are now vectorized.
-   New function `get_metadata_aemet()`.
-   New function `ggclimat_walter_lieth()`. This function is now the default for
    `climatogram_*` functions (experimental). Old behavior can be reproduced
    with options `ggplot2 = FALSE`.
-   Plot functions gains new parameters (`verbose` and `...`). Now it is
    possible to pass colors to the plotting functions.
-   New example datasets: `climaemet::climaemet_9434_climatogram`,
    `climaemet::climaemet_9434_temp`, `climaemet::climaemet_9434_wind`.
