Metadata-Version: 2.4
Name: pavdata
Version: 0.1.3
Summary: Transportation Infrastructure Data Toolbox
Author-email: Vilmar Faustino do Nascimento <vilmarfaustinok@gmail.com>, Carlos David Rodrigues Melo <cdavidmelo@ufc.br>, Nelson de Oliveira Quesado Filho <nquesado@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://cdavidrmelo.github.io/pavdata/
Project-URL: Repository, https://github.com/cdavidrmelo/pavdata
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic>=2.0
Requires-Dist: jsonschema>=4.0
Provides-Extra: viz
Requires-Dist: matplotlib>=3.7; extra == "viz"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Provides-Extra: all
Requires-Dist: matplotlib>=3.7; extra == "all"
Requires-Dist: pytest>=7.0; extra == "all"
Requires-Dist: ruff; extra == "all"
Dynamic: license-file

# PavData (Python)

<p>
  <a href="https://www.ufc.br/"><img src="https://github.com/cdavidrmelo/pavdata/raw/main/figs/logo_ufc.png" width="280" alt="UFC"></a>
  &nbsp;&nbsp;
  <a href="https://github.com/cdavidrmelo/pavdata"><img src="https://github.com/cdavidrmelo/pavdata/raw/main/figs/PavData.jpg" width="280" alt="PavData"></a>
</p>

![Version](https://img.shields.io/badge/version-0.1.2-blue.svg)
![Lifecycle: experimental](https://img.shields.io/badge/lifecycle-experimental-orange.svg)

`pavdata` is a Python 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). There is also an equivalent R package that
reads and writes the same format.

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 with familiar methods

## Installation

```bash
pip install pavdata
```

For the plotting functions, also install matplotlib:

```bash
pip install matplotlib
```

## Why pavdata?

Laboratory and field datasets in pavement engineering are often fragmented across
spreadsheets, scripts, and reports. `pavdata` provides a small relational layer 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:

```python
import pavdata

binder = pavdata.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 = pavdata.pav_new(
    "aggregate",
    id="aggregate-basalt",
    name="Basalt aggregate",
    bulk_specific_gravity=2.71,
    water_absorption_pct=1.2,
)

mixture = pavdata.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 = pavdata.pav_new(
    "mixture_test",
    id="test-volumetrics-dense-graded",
    name="Dense graded mix volumetrics",
    mixture_id=mixture.id,
    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,
    },
)
```

Validate the objects:

```python
pavdata.pav_check(binder)
pavdata.pav_check(mixture)
pavdata.pav_check(volumetrics)
```

Save them to disk and read them back:

```python
path = "example.pavdata"
pavdata.pav_write([binder, aggregate, mixture, volumetrics], path)

objects = pavdata.pav_read(path)
```

Load them into a library for indexed access:

```python
lib = pavdata.pav_library()
lib.load(path)

lib.pav_list(obj_type="mixture")
lib.pav_view(mixture.id)
```

## Inspecting Objects

Use `summary()` to display the populated fields of an object:

```python
volumetrics.summary()
```

In Python, graphical exploration is done through the `explore` module, which generates
figures from a `.pavdata` file:

```python
from pavdata import explore

explore.pav_explore(path)           # completeness dashboard
explore.pav_plot_volumetrics(path)  # air voids vs binder content
explore.pav_plot_mr(path)           # resilient modulus by binder
```

The R package produces equivalent plots through its `plot()` method, for example for
the volumetric properties of a mixture:

[![Bar plot of volumetric properties](https://github.com/cdavidrmelo/pavdata/raw/main/figs/readme-volumetrics-plot.png)](https://github.com/cdavidrmelo/pavdata/blob/main/figs/readme-volumetrics-plot.png)

## 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_completeness()`    | Report field completeness across a set     |

## 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 data classes and their relationships
([open full diagram](https://github.com/cdavidrmelo/pavdata/blob/main/figs/S3%20Class%20Pavdata%20Object-2026-06-08-111258.svg)).

## Built-In Example Data

The package ships with a dataset of 296 real samples, accessible through the
`SAMPLE_DATA_PATH` constant:

```python
import pavdata
data = pavdata.pav_read(pavdata.SAMPLE_DATA_PATH)
```

## 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)*. Associação Nacional de Pesquisa e Ensino
em Transportes. Goiânia, GO.

## Authors and Contributions

PavData is developed by the following authors:

- [**Vilmar Faustino do Nascimento**](http://lattes.cnpq.br/5613705610783390) — Package development, implementation, and maintenance.
- [**Carlos David Rodrigues Melo**](http://lattes.cnpq.br/2195069070025642) — Project conception, scientific coordination, database design, machine learning modeling, and modeling framework.
- [**Nelson de Oliveira Quesado Filho**](https://lattes.cnpq.br/0402241557904425) — Software supervision, R implementation support, and data organization.
- [**Jorge Barbosa Soares**](http://lattes.cnpq.br/9212256013670303) — Academic supervision, conceptual guidance, and pavement engineering contribution.
- [**Evandro Parente Junior**](https://lattes.cnpq.br/1774654203813780) — Academic co-supervision and computational mechanics contribution.

## Affiliation

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

## License

The software is distributed under the MIT license. The example data that ships with the
library is distributed under the CC-BY-4.0 license.

## Links

- Project site: https://cdavidrmelo.github.io/pavdata/
- Repository: https://github.com/cdavidrmelo/pavdata
