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

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

```{r setup, echo=FALSE}
library(phscs)
```

The `phscs` package provides a single, consistent interface to seven Philippine Statistical Authority (PSA) classification systems. All data is **bundled with the package** — no internet connection or API token is required.

| Function | Classification | Source |
|---|---|---|
| `get_psgc()` | Philippine Standard Geographic Code | PSA via `psgc` |
| `get_psic()` | Philippine Standard Industrial Classification | PSA |
| `get_psoc()` | Philippine Standard Occupational Classification | PSA |
| `get_psced()` | Philippine Standard Classification of Education | PSA |
| `get_pcoicop()` | Phil. Classification of Individual Consumption According to Purpose | PSA |
| `get_pcpc()` | Philippine Central Product Classification | PSA |
| `get_psccs()` | Philippine Standard Commodity Classification System | PSA |

## Installation

Install from CRAN:

```r
install.packages("phscs")
```

Or install the development version from GitHub:

```r
# install.packages("pak")
pak::pak("yng-me/phscs")
```

## Common interface

All classification functions share the same parameters:

| Parameter | Default | Description |
|---|---|---|
| `version` | latest | Which edition of the standard to use (e.g. `"2019"`, `"2009"`) |
| `level` | most detailed | Which level of the hierarchy to return |
| `minimal` | `TRUE` | Return only `value` and `label`; set `FALSE` for all columns |
| `cols` | `NULL` | Extra columns to include alongside `value` and `label` (e.g. `"description"`) |

Every classification has a `description` column available via `cols = "description"`:

```{r common-cols}
get_psic(level = "sections", cols = "description") |>
  head(5) |>
  gt::gt() |>
  gt::tab_options(table.align = "left")
```

## Philippine Standard Geographic Code (PSGC)

`get_psgc()` is re-exported from the [`psgc`](https://cran.r-project.org/package=psgc) package. For a full walkthrough — releases, crosswalks, population data — see `vignette("psgc", package = "psgc")`.

Use `geographic_level` to filter to a specific tier:

```{r psgc-regions}
psgc_regions <- get_psgc(geographic_level = "region")

psgc_regions |>
  gt::gt() |>
  gt::tab_options(table.align = "left")
```

Use `shorten_region_name()` to compact long region labels for plots or tables:

```{r psgc-shorten}
psgc_regions |>
  shorten_region_name(which = "label") |>
  head(5) |>
  gt::gt() |>
  gt::tab_options(table.align = "left")
```

To filter rows by code, use standard R subsetting after the call:

```{r psgc-filter, eval=FALSE}
# All areas whose PSGC code starts with "10" (Region X)
psgc_all <- get_psgc()
psgc_region_10 <- psgc_all[grepl("^10", psgc_all$psgc_code), ]
```

## Philippine Standard Industrial Classification (PSIC)

The [PSIC](https://psa.gov.ph/classification/psic) organises economic activities into sections, divisions, groups, classes, and sub-classes. The default returns the most detailed level.

```{r psic-default}
get_psic() |>
  head(10) |>
  gt::gt() |>
  gt::tab_options(table.align = "left")
```

```{r psic-sections}
get_psic(level = "sections") |>
  gt::gt() |>
  gt::tab_options(table.align = "left")
```

## Philippine Standard Occupational Classification (PSOC)

The [PSOC](https://psa.gov.ph/classification/psoc) classifies occupations into major, sub-major, minor, and unit groups. The default returns unit groups.

```{r psoc-default}
get_psoc() |>
  head(10) |>
  gt::gt() |>
  gt::tab_options(table.align = "left")
```

```{r psoc-major}
get_psoc(level = "major") |>
  gt::gt() |>
  gt::tab_options(table.align = "left")
```

## Philippine Standard Classification of Education (PSCED)

The [PSCED](https://psa.gov.ph/classification/psced) classifies fields of study into education levels, broad fields, narrow fields, and detailed fields. The default returns detailed fields.

```{r psced-default}
get_psced() |>
  head(10) |>
  gt::gt() |>
  gt::tab_options(table.align = "left")
```

```{r psced-levels}
get_psced(level = "levels") |>
  gt::gt() |>
  gt::tab_options(table.align = "left")
```

## Philippine Classification of Individual Consumption According to Purpose (PCOICOP)

The [PCOICOP](https://psa.gov.ph/classification/pcoicop) classifies household expenditures. Two editions are available: `"2020"` (default, 3,472 items) and `"2009"` (1,722 items).

```{r pcoicop-default}
get_pcoicop() |>
  head(10) |>
  gt::gt() |>
  gt::tab_options(table.align = "left")
```

```{r pcoicop-divisions}
get_pcoicop(level = "divisions") |>
  gt::gt() |>
  gt::tab_options(table.align = "left")
```

Switch to the 2009 edition with `version = "2009"`:

```{r pcoicop-2009}
get_pcoicop(version = "2009", level = "divisions") |>
  gt::gt() |>
  gt::tab_options(table.align = "left")
```

## Philippine Central Product Classification (PCPC)

The [PCPC](https://psa.gov.ph/classification/pcpc) classifies goods and services. The default returns all 8,734 items across six levels.

```{r pcpc-default}
get_pcpc() |>
  head(10) |>
  gt::gt() |>
  gt::tab_options(table.align = "left")
```

```{r pcpc-sections}
get_pcpc(level = "sections") |>
  gt::gt() |>
  gt::tab_options(table.align = "left")
```

## Philippine Standard Commodity Classification System (PSCCS)

The [PSCCS](https://psa.gov.ph/classification/psccs) classifies commodities into sections, divisions, groups, classes, and sub-classes. The default returns all 1,870 items.

```{r psccs-default}
get_psccs() |>
  head(10) |>
  gt::gt() |>
  gt::tab_options(table.align = "left")
```

```{r psccs-section}
get_psccs(level = "section") |>
  gt::gt() |>
  gt::tab_options(table.align = "left")
```