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

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

This article walks through a typical ineptr2 workflow: creating a client, exploring an indicator, and fetching data.

## Install and load

```r
# From GitHub
devtools::install_github("c-matos/ineptr2")

```

```{r}
library(ineptr2)
```

## Create a client

The `INEClient` object holds your configuration — language, caching preferences, timeouts — so you don't have to repeat them on every call.

```{r}
ine <- INEClient$new(lang = "EN")
ine
```

You can change settings at any time:

```{r}
ine$lang <- "PT"
ine$lang <- "EN"
```

## Inspect an indicator

Suppose you want to work with indicator `"0008273"` (Resident population). Start by checking what it contains:

```{r}
ine$info("0008273")
```

This shows the indicator name, periodicity, time range, last update date, and a breakdown of dimensions with their sizes.

For more detail on each dimension, use `get_dim_info()`:

```{r}
ine$get_dim_info("0008273")
```

To see the actual values available in each dimension:

```{r}
# All dimensions
vals <- ine$get_dim_values("0008273")
head(vals)

# Only dimensions 1 and 3
ine$get_dim_values("0008273", dims = c(1, 3))
```

The `categ_cod` column contains the codes you pass to `get_data()` as dimension filters.

## Preview before downloading

Before fetching data, you can check how many API requests will be needed. 1 API request = 1 chunk:

```{r}
ine$preview_chunks("0008206")
```

This is especially useful for large indicators. You can also preview with filters to see how they reduce the number of chunks:

```{r}
ine$preview_chunks("0008206", dim1 = "S7A2023")
```

## Fetch data

The simplest way to get data is `get_data()`, which downloads and processes in one step:

```{r}
df <- ine$get_data("0008273", dim1 = "S7A2023", dim2 = c("PT", "1", "2", "3"))
head(df)
```

Dimension filters use the `categ_cod` values from `get_dim_values()`. If you omit a dimension, all values are returned.

## Download large indicators

For large indicators, you may prefer to download first and load later. This streams data to disk without holding it in memory:

```{r}
ine$use_cache <- TRUE
ine$cache_dir <- "C:/R/my_cache_dir"
ine$download_data("0008273", dim1 = "S7A2023")
```

If a download is interrupted, calling `download_data()` again resumes from where it left off.

Load the raw data later (even in a new session):

```{r}
raw <- ine$load_raw_data("0008273")
str(raw, max.level = 2)
```



## Enable caching

By default, every call hits the API. Enable caching to avoid redundant requests:

```{r}
ine$use_cache <- TRUE
```

With caching on, `get_data()` stores the processed result. Subsequent calls with the same or narrower filters are served from cache. See the [How caching works](https://c-matos.github.io/ineptr2/articles/caching.html) article for details.

## Check for updates

If you've previously downloaded data and want to know whether the indicator has been updated since:

```{r}
ine$is_updated("0008273", metadata = ine$get_metadata("0008273"))
# OR
ine$is_updated("0008273", last_updated = "2024-01-01")
```

Assuming you had cached metadata for indicator `0008206`, the field `DataUltimaAtualizacao` would be used. Alternatively, provide a specific `last_updated` date.

## Validate an indicator

Not sure if an indicator code exists?

```{r}
ine$is_valid("0008273")
ine$is_valid("0000000")
```

## Browse the indicator catalog

Not sure which indicator you need? You can download the full INE catalog — a table with all 13,000+ indicators, their codes, names, and themes:

```r
ine$download_catalog()
catalog <- ine$get_catalog()
head(catalog)
```

The catalog download is slow (~10 minutes) but is cached on disk, so subsequent calls return instantly.

## Switch language

All output, including dimension labels and descriptions, follows the client's language setting:

```{r}
ine_pt <- INEClient$new(lang = "PT")
ine_pt$info("0008273")
```

## Clear cache

No longer need the indicator? Clean the cache on your way out.


```{r}
# cleanup - single indicator
ine$clear_cache("0008273")

# everything
# WARNING: This will remove `cache_dir` and all its contents.
ine$clear_cache()
```