---
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 = "#>"
)

library(fcall)
```

### Downloading Data

You can download data for a particular period using `download_data()`:

```{r, eval=FALSE}
library(fcall)

# Download FCA Call Report data from March 2023
download_data(
  year = 2023,
  month = 3,
  dest = "path/to/some/folder"
)
```

### Processing Files

You can parse the data from the downloaded *.TXT* files into tidy R data frames using `process_data()`:

```{r, eval=FALSE}
# Process data from March 2023
data_2023_03 <- process_data(dir = "path/to/some/folder")
```

You can also use `process_metadata_file()` and `process_data_file()` to process single metadata and data files, respectively.

**Note: `process_data()` has only been tested by the development team on Call Report data from March 2020 to present. Please let us know if you find issues with processing data older than 2020.**

### Comparing Metadata from Different Periods

The FCA Call Report data has changed over time, making it difficult to perform analysis across multiple periods. To ensure that such comparisons can be made safely, the `compare_metadata()` returns differences in the data structure (files, column names, and column definitions) between two sets of FCA Call Report data.

```{r, eval=FALSE}
# Download data from June 2023
download_data(
  year = 2023,
  month = 6,
  dest = "path/to/some/other/folder"
)

# Compare metadata files from March and June 2023
compare_metadata(
  dir1 = "path/to/some/folder",   # where we downloaded the March 2023 data
  dir2 = "path/to/some/other/folder"
)
```

### Internal Datasets

{fcall} contains the following internal datasets:

* `file_metadata` contains a short description about each file.
* The remaining datasets represent a series of "lookup table" dictionaries for the mapping between integer codes in the raw data and their plain-English descriptions in the associated metadata. These datasets follow the naming convention `<file>__<column>`, where `file` is the name of the raw data file and `column` is the name of the column in the associated metadata file for which the dataset provides the codes/definition mapping. For example, the `RCB` Call Report data includes the column `INV_CODE`; the `RCB__INV_CODE` internal dataset in {fcall} provides the mapping between these integer codes and the associated plain-English definitions for each.

```{r}
RCB__INV_CODE |> str()
```

To streamline data retrieval and usage, a dedicated function named `get_codes_dict()` is also available. This function allows users to access code dictionaries for a dataset without needing to remember the specific column name in the dataset that contains the codes:

```{r}
# Get codes dictionary information for "RCB" data
get_codes_dict("RCB") |> str()
```