README.qmd

---
format: gfm
default-image-extension: ''
knitr:
  opts_chunk:
    collapse: true
    comment: "#>"
    warning: false
    message: false
    dev: "ragg_png"
    tidy: "styler"
    fig.path: "man/figures/README-"
    dpi: 300
    out.width: "100%"
---

<!-- README.md is generated from README.qmd. Please edit that file -->

```{r}
#| label: knitr
#| include: false
httr2::local_verbosity(0)
```

# climaemet <a href="https://ropenspain.github.io/climaemet/"><img src="man/figures/logo.png" alt="climaemet website" align="right" height="139"/></a>

<!-- badges: start -->

[![rOS-badge](https://ropenspain.github.io/rostemplate/reference/figures/ropenspain-badge.svg)](https://ropenspain.es/)
[![CRAN
status](https://www.r-pkg.org/badges/version/climaemet)](https://CRAN.R-project.org/package=climaemet)
[![CRAN_time_from_release](https://www.r-pkg.org/badges/ago/climaemet)](https://cran.r-project.org/package=climaemet)
[![CRAN_latest_release_date](https://www.r-pkg.org/badges/last-release/climaemet)](https://cran.r-project.org/package=climaemet)
[![CRAN
results](https://badges.cranchecks.info/worst/climaemet.svg)](https://cran.r-project.org/web/checks/check_results_climaemet.html)
[![r-universe](https://ropenspain.r-universe.dev/badges/climaemet)](https://ropenspain.r-universe.dev/climaemet)
[![R-CMD-check](https://github.com/rOpenSpain/climaemet/actions/workflows/roscron-check-full.yaml/badge.svg)](https://github.com/rOpenSpain/climaemet/actions/workflows/roscron-check-full.yaml)
[![codecov](https://codecov.io/gh/rOpenSpain/climaemet/graph/badge.svg?token=ZD3FL138Z4)](https://app.codecov.io/gh/rOpenSpain/climaemet)
[![DOI](https://img.shields.io/badge/DOI-10.5281/zenodo.5205573-blue)](https://doi.org/10.5281/zenodo.5205573)
[![metacran
downloads](https://cranlogs.r-pkg.org/badges/climaemet)](https://cran.r-project.org/package=climaemet)
![GitHub
License](https://img.shields.io/github/license/rOpenSpain/climaemet?color=blue)
[![Project Status: Active -- The project has reached a stable, usable state and
is being actively
developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active)

<!-- badges: end -->

**climaemet** provides access to meteorological observations, forecasts, alerts
and climatology data from the Spanish Meteorological Agency (AEMET). It also
includes tools for working with tabular and spatial data and for creating
Walter-Lieth climate diagrams, warming stripes and wind roses.

Browse the manual and vignettes at <https://ropenspain.github.io/climaemet/>.

## AEMET OpenData API

**AEMET OpenData** is a REST API for accessing and reusing AEMET's
meteorological and climatological information. For details, visit
<https://opendata.aemet.es/centrodedescargas/inicio>.

## License for the original data

The data are prepared by the Spanish Meteorological Agency (© AEMET). See the
[AEMET legal notice](https://www.aemet.es/en/nota_legal) for details.

A summary of data usage is:

> People can use these data freely. You should mention AEMET as the collector of
> the original data in every situation except when you are using these data
> privately and individually. AEMET makes no warranty as to the accuracy or
> completeness of the data. All data are provided on an "as is" basis. AEMET is
> not responsible for any damage or loss derived from the interpretation or use
> of these data.

## Installation

Install the released version of **climaemet** from
[**CRAN**](https://CRAN.R-project.org) with:

```{r}
#| eval: false
install.packages("climaemet")
```

Install the development version of **climaemet** from
[**r-universe**](https://ropenspain.r-universe.dev/climaemet):

```{r}
#| eval: false
# Install climaemet in R:
install.packages(
  "climaemet",
  repos = c(
    "https://ropenspain.r-universe.dev",
    "https://cloud.r-project.org"
  )
)
```

Alternatively, install the development version of **climaemet** with:

```{r}
#| eval: false
# install.packages("pak")
pak::pak("ropenspain/climaemet")
```

## API key

To download data from AEMET, obtain a free API key from the [**AEMET OpenData**
registration page](https://opendata.aemet.es/centrodedescargas/altaUsuario).

```{r}
#| eval: false
library(climaemet)

# Open the AEMET OpenData registration page.
browseURL("https://opendata.aemet.es/centrodedescargas/altaUsuario")

# Set the API key for the current R session.
aemet_api_key("MY API KEY")
```

## Migrating from versions before 1.0.0

Versions before 1.0.0 accepted an `apikey` argument in data-access functions.
Current code should set the API key globally with `aemet_api_key()` and remove
the obsolete `apikey` argument.

## Data formats

### Tabular results

**climaemet** returns tabular results as [**tibble**
objects](https://tibble.tidyverse.org/). The package also infers column types
when possible. For example, date and time columns are parsed as date-time
objects and numeric columns are parsed as doubles.

```{r}
#| label: tibble
#| message: true
library(climaemet)

# Inspect a tibble.

aemet_last_obs("9434")
```

### Spatial outputs

Data-access functions that support `return_sf = TRUE` can return spatial **sf**
objects. These objects use the EPSG:4326 coordinate reference system (CRS),
corresponding to the World Geodetic System 1984 (WGS 84), with unprojected
longitude and latitude coordinates:

```{r}
#| label: spatial
#| fig-cap: Map created with climaemet and sf.
# You need to install sf if it is not already installed.
# Run install.packages("sf") to install it.
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 = "Mean temp.\n(°C)",
    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")
  )
```

## Plots

You can create warming stripes from temperature data recorded at weather
stations. The plotting functions return **ggplot2** objects:

```{r}
#| label: climatestripes
#| eval: true
#| fig-asp: 0.7
#| fig-cap: Warming stripes created with climaemet.
# Plot warming stripes for a weather station.

library(ggplot2)

# Load example data.
temp_data <- climaemet::climaemet_9434_temp

ggstripes(temp_data, plot_title = "Zaragoza Airport") +
  labs(subtitle = "(1950-2020)")
```

You can also create a Walter-Lieth climate diagram for a weather station over a
specified period:

```{r}
#| label: climatogram
#| eval: true
#| fig-asp: 0.7
#| fig-cap: Walter-Lieth climate diagram for a weather station.
# Plot a Walter-Lieth climate diagram for a weather station.

# Load example data.
wl_data <- climaemet::climaemet_9434_climatogram

ggclimat_walter_lieth(
  wl_data,
  alt = "249",
  per = "1981-2010",
  est = "Zaragoza Airport"
)
```

You can also create a wind rose from wind speed and direction data recorded at
weather stations.

```{r}
#| label: windrose
#| eval: true
#| fig-asp: 0.7
#| fig-cap: Wind rose showing wind speed and direction.
# Plot a wind rose for a weather station.

# Load example data.
wind_data <- climaemet::climaemet_9434_wind

speed <- wind_data$velmedia
direction <- wind_data$dir

ggwindrose(
  speed = speed,
  direction = direction,
  speed_cuts = seq(0, 16, 4),
  legend_title = "Wind speed (m/s)",
  calm_wind = 0,
  n_col = 1,
  plot_title = "Zaragoza Airport"
) +
  labs(subtitle = "2000-2020", caption = "Source: AEMET")
```

```{r}
#| label: stopdefer
#| include: false
withr::deferred_clear()
```

## Code of conduct

This project is released with a Contributor Code of Conduct. By participating,
you agree to abide by its terms.

## Citation

If you use **climaemet** in a paper, please consider citing it:

```{r}
#| echo: false
#| results: asis
print(citation("climaemet")[1], style = "html")
```

A **BibTeX** entry for **LaTeX** users is:

```{r}
#| echo: false
#| comment: ''
toBibtex(citation("climaemet")[1])
```

## Links

- Download **climaemet** from <https://cran.r-project.org/package=climaemet>.
- Browse the source code at <https://github.com/ropenspain/climaemet>.