# PavData <img src="figs/logo_ufc.png" alt="Universidade Federal do Ceará" width="180" align="right"> <img src="figs/PavData.jpeg" alt="PavData Logo" width="120" align="right">

[![Version](https://img.shields.io/badge/version-0.1.0-blue.svg)](#installation)
[![Lifecycle: experimental](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://lifecycle.r-lib.org/articles/stages.html#experimental)

`pavdata` is an [R](https://www.r-project.org/) package for storing,
validating, and exploring transportation infrastructure data with a
lightweight, human-readable `.pavdata` format based on
[JSON](https://www.json.org/json-en.html).

It is designed for pavement and materials workflows where researchers need to:

- create structured objects for samples, binders, aggregates, mixtures, and tests
- validate required fields and plausible numeric ranges
- serialize data to a portable file format
- reload collections into an indexed in-memory library
- inspect objects interactively with familiar R methods such as `print()`, `summary()`, and `plot()`

## Installation

Install from a local source tree:

```r
install.packages("path/to/pavdata", repos = NULL, type = "source")
```

After its first release on [CRAN](https://cran.r-project.org/), install it with:

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

## Why pavdata?

Laboratory and field datasets in pavement engineering are often fragmented across spreadsheets, scripts, and reports. `pavdata` provides a small relational layer in R so those records can be created, checked, saved, and reused more consistently.

The package focuses on four practical ideas aligned with the
[FAIR Principles](https://www.go-fair.org/fair-principles/):

- explicit object types for common pavement entities
- built-in validation for required fields and plausible ranges
- reproducible read/write support through `.pavdata` files
- simple tools for browsing collections during analysis

## Quick Start

Create a few linked objects:

```r
library(pavdata)

binder <- pav_new(
  "binder",
  id = "binder-cap-50-70",
  name = "CAP 50/70",
  binder_type = "CAP 50/70",
  penetration_mm = 52,
  softening_point_c = 49
)

aggregate <- pav_new(
  "aggregate",
  id = "aggregate-basalt",
  name = "Basalt aggregate",
  bulk_specific_gravity = 2.71,
  water_absorption_pct = 1.2
)

mixture <- pav_new(
  "mixture",
  id = "mixture-dense-graded",
  name = "Dense graded mix",
  binder_id = binder$id,
  aggregate_id = aggregate$id,
  binder_content_pct = 5.3
)

volumetrics <- pav_new(
  "mixture_test",
  id = "test-volumetrics-dense-graded",
  name = "Dense graded mix volumetrics",
  mixture_id = mixture$id,
  test_type = "volumetrics",
  volumetrics = list(
    air_voids_pct = 4.1,
    voids_mineral_aggregate_pct = 15.4,
    voids_filled_asphalt_pct = 73.4,
    filler_binder_ratio = 1.1
  )
)
```

Validate the objects:

```r
pav_check(binder)
pav_check(mixture)
pav_check(volumetrics)
```

Save them to disk and read them back:

```r
path <- tempfile(fileext = ".pavdata")
pav_write(list(binder, aggregate, mixture, volumetrics), path)

objects <- pav_read(path)
names(objects)
```

Load them into a library for indexed access:

```r
lib <- pav_library()
pav_library_load(lib, path)

print(lib)
pav_list(lib, type = "mixture")
pav_view(lib, mixture$id)
```

## Inspecting Objects

PavData objects support standard [S3](https://adv-r.hadley.nz/s3.html)
methods.

### `print()`

Use `print()` for a compact object overview:

```r
print(binder)
```

```text
<pavdata_binder> CAP 50/70
  id: binder-cap-50-70 | v1 | 13 fields
```

### `summary()`

Use `summary()` to display the populated metadata and data fields:

```r
summary(volumetrics)
```

```text
MIXTURE_TEST: Dense graded mix volumetrics
ID: test-volumetrics-dense-graded | v1 | Created: <timestamp>
Source:
mixture_id                     mixture-dense-graded
test_type                      volumetrics
volumetrics
  air_voids_pct                4.1
  voids_mineral_aggregate_pct  15.4
  voids_filled_asphalt_pct     73.4
  filler_binder_ratio          1.1
```

### `plot()`

Use `plot()` to compare numeric fields. Short labels can be passed to the
underlying base-R bar plot with `names.arg`:

```r
plot(
  volumetrics,
  names.arg = c("Air voids (%)", "VMA (%)", "VFA (%)", "Filler/binder"),
  ylim = c(0, 80)
)
```

<p align="center">
  <img src="figs/readme-volumetrics-plot.png"
       alt="Bar plot of volumetric properties generated by plot()"
       width="850">
</p>

## Main Functions

| Function | Purpose |
| --- | --- |
| `pav_new()` | Create a new PavData object |
| `pav_check()` | Validate one object |
| `pav_check_integrity()` | Validate a collection and its foreign keys |
| `pav_write()` | Write objects to a `.pavdata` file |
| `pav_read()` | Read objects from a `.pavdata` file |
| `pav_load()` | Read a file and validate all objects |
| `pav_library()` | Create an in-memory indexed library |
| `pav_library_load()` | Load a file into a library |
| `pav_list()` | List objects in a library |
| `pav_view()` | Display one object from a library |

## Object Types

`pavdata` currently supports these object families:

- `sample`
- `binder`
- `aggregate`
- `mixture`
- `binder_test`
- `aggregate_test`
- `mixture_test`
- `reference`

Each object shares common metadata such as `id`, `name`, `type`, `version`, `created_at`, `source`, and `notes`.

## UML Data Model

The UML diagram below summarizes the S3 classes and their relationships.

<p align="center">
  <img src="figs/S3%20Class%20Pavdata%20Object-2026-06-08-111258.svg"
       alt="UML diagram of PavData S3 classes"
       width="900">
</p>

## Built-In Example Data

The package ships with an example `.pavdata` file:

```r
path <- pavdata_sample_path()
path
```

You can use it to test import, browsing, and validation workflows.

## Related Publications

- Melo, C. D. R., Carvalho, P. H. J., Mariano, L. G., Babadopulos, L. F. A. L.,
Parente Junior, E., and Soares, J. B. (2025). **Proposta preliminar de um
repositório nacional aberto de ensaios de misturas asfálticas**. In *Anais do
39º Congresso de Pesquisa e Ensino em Transportes (39º ANPET)* [electronic
book]. Associação Nacional de Pesquisa e Ensino em Transportes. Goiânia, GO.


## Authors and Affiliation
PavData is developed by:

Creator

- [Vilmar Faustino do Nascimento](http://lattes.cnpq.br/5613705610783390)

Authors

- [Carlos David Rodrigues Melo](http://lattes.cnpq.br/2195069070025642)
- [Nelson de Oliveira Quesado Filho](https://lattes.cnpq.br/0402241557904425)

Contributors

- [Jorge Barbosa Soares](http://lattes.cnpq.br/9212256013670303)

Affiliation

- [Universidade Federal do Ceará (UFC)](https://www.ufc.br/)
