pavdata 0.1.3

Transportation Infrastructure Data Toolbox

PavData (Python)

  

pavdata is a Python package for storing, validating, and exploring transportation infrastructure data with a lightweight, human-readable .pavdata format based on JSON. 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

pip install pavdata

For the plotting functions, also install matplotlib:

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:

• 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:

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:

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

Save them to disk and read them back:

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

objects = pavdata.pav_read(path)

Load them into a library for indexed access:

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:

volumetrics.summary()

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

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:

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).

Built-In Example Data

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

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 — Package development, implementation, and maintenance.
• Carlos David Rodrigues Melo — Project conception, scientific coordination, database design, machine learning modeling, and modeling framework.
• Nelson de Oliveira Quesado Filho — Software supervision, R implementation support, and data organization.
• Jorge Barbosa Soares — Academic supervision, conceptual guidance, and pavement engineering contribution.
• Evandro Parente Junior — Academic co-supervision and computational mechanics contribution.

Affiliation

• Universidade Federal do Ceará (UFC)

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