---
title: "Getting Started with rmet"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Getting Started with rmet}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.width = 7,
  fig.height = 4,
  fig.align = "center",
  dpi = 150
)
```

Brazil's National Institute of Meteorology (INMET) runs a network of more than
600 automatic weather stations that record hourly observations. Historical
data are published as one ZIP archive per year, holding one CSV file per
station, with formats that changed several times over the years. `rmet`
downloads and caches those archives, reads them into consistent data frames,
and summarises the hourly data into daily values.

```{r install, eval = FALSE}
install.packages("rmet")
```

```{r library}
library(rmet)
```

## Find a station

`inmet_stations()` returns the official catalogue of automatic stations. It is
downloaded from INMET once and cached; when INMET cannot be reached, a snapshot
bundled with the package is used instead.

```{r stations}
rs <- inmet_stations(state = "RS", status = "Operante", source = "bundled")
head(rs[, c("station_code", "station_name", "latitude", "longitude", "start_date")])
```

(`source = "bundled"` keeps this vignette reproducible offline. In your own
code, leave `source` at its default to get the current catalogue.)

To find the stations closest to a place, use `inmet_nearest()`:

```{r nearest}
inmet_nearest(latitude = -30.03, longitude = -51.23, n = 3, source = "bundled")[
  , c("station_code", "station_name", "distance_km", "start_date")
]
```

Station **A801** (Porto Alegre - Jardim Botanico) has been operating since
September 2000. The catalogue also gives each station's local `time_zone`.

With the **sf** package installed, `inmet_as_sf()` turns the catalogue (or
any result with coordinates) into spatial points:

```{r map, eval = requireNamespace("sf", quietly = TRUE), fig.cap = "Operating automatic stations in Rio Grande do Sul, by elevation."}
plot(inmet_as_sf(rs)["elevation"], pch = 19, main = "")
```

## Get hourly data

`inmet_get()` downloads any missing archives and reads the stations you ask
for:

```{r get, eval = FALSE}
poa <- inmet_get(
  years = 2023,
  stations = "A801",
  variables = c("temp_dry_c", "temp_max_prev_c", "temp_min_prev_c", "precip_mm")
)
```

The first call downloads the archive for each year, around 100 MB for recent
years; later calls read from the cache. For the current and the previous year,
`rmet` also checks whether INMET has published a newer version of the archive
(INMET keeps adding data to them) and downloads it if so.

The package ships the result of `inmet_get(2023, stations = "A801")` as
`rmet_example`, which the rest of this vignette uses:

```{r example}
dim(rmet_example)
head(rmet_example[, c("datetime", "temp_dry_c", "temp_max_prev_c", "precip_mm")])
```

Timestamps are in **UTC**, as in the source files, and each row describes the
hour *ending* at `datetime`. Pass `tz = "America/Sao_Paulo"` (or any other
Olson name) to `inmet_get()` or `inmet_read()` to display them in local time.

## Quality control and completeness

INMET publishes these observations as raw data. `inmet_qc()` flags values
that are physically impossible, internally inconsistent, isolated spikes, or
stuck at the same value, and `inmet_completeness()` shows how many valid hours
each month has:

```{r qc}
checked <- inmet_qc(rmet_example)
head(inmet_completeness(checked, variables = c("temp_dry_c", "precip_mm")), 3)
```

## Daily summaries

Most analyses need daily values. `inmet_daily()` assigns each hour to the
station's local day, ignores values flagged by `inmet_qc()`, and requires a
minimum number of valid hours per day (20 by default):

```{r daily}
daily <- inmet_daily(checked)
head(daily[, c("date", "n_hours", "temp_max_c", "temp_min_c", "precip_mm")])
```

The first row is 31 December 2022: the records stamped 00:00 to 03:00 UTC on
1 January 2023 describe the last hours of 31 December in Porto Alegre. With
only four hours of data that day's values are `NA`. See `vignette("daily-data", package = "rmet")` for the details
and why `as.Date(datetime)` gives the wrong days.

```{r plot-temp, fig.cap = "Daily maximum and minimum temperature at Porto Alegre (A801), 2023."}
daily <- daily[format(daily$date, "%Y") == "2023", ]
oldpar <- par(mar = c(4, 4.5, 2, 1))
plot(daily$date, daily$temp_max_c, type = "l", col = "#C0392B",
     ylim = range(daily$temp_min_c, daily$temp_max_c, na.rm = TRUE),
     xlab = "", ylab = "Temperature (°C)")
lines(daily$date, daily$temp_min_c, col = "#2471A3")
legend("topright", c("Maximum", "Minimum"), col = c("#C0392B", "#2471A3"),
       lwd = 1, bty = "n")
par(oldpar)
```

```{r plot-precip, fig.cap = "Monthly precipitation at Porto Alegre (A801), 2023."}
monthly <- tapply(daily$precip_mm, format(daily$date, "%m"), sum, na.rm = TRUE)
oldpar <- par(mar = c(4, 4.5, 2, 1))
barplot(monthly, names.arg = month.abb, col = "#5DADE2", border = NA,
        ylab = "Precipitation (mm)")
par(oldpar)
```

Days with missing precipitation hours are `NA` in `daily$precip_mm`, so these
monthly totals are lower bounds when data are missing; check `n_hours`.

## Step-by-step workflow

`inmet_get()` combines three steps that can also be run separately:

```{r steps, eval = FALSE}
inmet_download(2020:2023)        # download (or update) archives
inmet_cache_status()             # what is cached, and how large
weather <- inmet_read(
  years = 2020:2023,
  stations = c("A801", "A832"),
  start_date = "2020-06-01",
  end_date = "2023-08-31",
  variables = c("temp_dry_c", "precip_mm")
)
```

Reading only the stations and variables you need keeps memory use low: one
year of every station is about four million rows. `inmet_extract()` copies the
original CSV files out of the archives if you need them for other software, and
`inmet_cache_clear()` frees disk space.

## Data quality

INMET publishes automatic-station data as raw measurements without
consistency checks. `inmet_qc()` catches gross errors, but it cannot judge
every value. Apply further checks appropriate to your analysis, such as
comparison with neighbouring stations, before drawing conclusions.

The variables returned and their units are listed in `?inmet_read`; daily
variables are described in `?inmet_daily`.