pivmetalib

A Python library and high-level interface to work with the pivmeta ontology. It allows you to describe PIV recordings, software, hardware and other related entities in a state-of-the-art and scientifically compliant way.

The library depends on ontolutils, which provides the object-oriented interface to the ontology and the JSON-LD serialization.

🚀 Quick Start

Install the package and create your first PIV metadata in minutes:

pip install pivmetalib

from pivmetalib import pivmeta, prov

# Describe PIV software
software = pivmeta.PIVSoftware(
    author=prov.Organization(
        name='OpenPIV',
        url='https://github.com/OpenPIV/openpiv-python',
    ),
    description='OpenPIV is an open source Particle Image Velocimetry analysis software',
    softwareVersion="0.26.0a0",
    hasDocumentation='https://openpiv.readthedocs.io/en/latest/',
)

# Export to JSON-LD for FAIR data sharing
print(software.serialize("jsonld"))

**📚 Want to learn more? ** → Complete User Guide | Examples | API Reference

📖 Table of Contents

• What You Can Do with pivmetalib
• Installation
• User Journey Guide
• Key Features
• Documentation
• Examples
• Contribution
• Troubleshooting

🎯 What You Can Do with pivmetalib

For Researchers

• Document PIV Experiments: Create comprehensive metadata for your recordings, setups, and processing steps
• FAIR Data Compliance: Export standardized metadata that makes your data findable, accessible, interoperable, and reusable
• Reproducible Research: Capture complete experimental configurations for scientific reproducibility
• Data Processing Pipelines: Document complex PIV processing workflows with provenance
• Tool Interoperability: Enable metadata exchange between different PIV tools
• Long-term Preservation: Store metadata in standards-compliant formats (JSON-LD, TTL)

💻 Installation

Basic Installation

The package is available on PyPI and can be installed via pip:

pip install pivmetalib

Development Installation

For development or to access additional dependencies:

# Install with test dependencies
pip install pivmetalib[test]

# Install with all optional dependencies
pip install pivmetalib[complete]

# Install from source for development
git clone https://github.com/matthiasprobst/pivmetalib.git
cd pivmetalib
pip install -e .[test]

Verify Installation

import pivmetalib
print(f"pivmetalib version: {pivmetalib.__version__}")

🗺️ User Guide

Choose your path based on your background and goals:

New to PIV Metadata?

1. Start with Getting Started Tutorial - Learn basic concepts
2. Describe Your First Recording - Complete dataset workflow
3. PIV Processing with OpenPIV - Processing pipeline documentation
4. Result File Documentation - Publishing your results

Key Features

Comprehensive PIV Metadata

• Hardware Description: Digital cameras, lasers, optical components, objectives
• Software Documentation: PIV analysis tools, processing parameters, version control
• Experimental Setups: Virtual and experimental configurations
• Processing Pipelines: Complete PIV analysis workflows with provenance

Data Quality Management

• Flag Schemes: Flexible flag system for data quality indicators
• Validation: Built-in type checking and constraint validation
• Standard Names: Integration with PIV standard name tables for consistent terminology

Format Flexibility

• Multiple Exports: JSON-LD, Turtle (TTL), XML serialization
• Namespace Support: Integration with schema.org, PROV, DCAT, M4I ontologies
• Query Capabilities: SPARQL queries and data retrieval from JSON-LD files

FAIR Compliance

• Findable: Rich metadata with standardized identifiers
• Accessible: Multiple export formats for different tools
• Interoperable: Ontology-based approach for data exchange
• Reusable: Complete provenance and documentation

💡 Examples

🚀 Quick Examples

Describe PIV Software:

from pivmetalib import pivmeta, prov

software = pivmeta.PIVSoftware(
    author=prov.Organization(name='OpenPIV'),
    softwareVersion="0.26.0a0",
    description='Open source Particle Image Velocimetry analysis software'
)

Export to Different Formats:

# JSON-LD
jsonld_data = software.serialize("jsonld")

# Turtle (TTL)  
ttl_data = software.serialize("ttl")

# XML
xml_data = software.serialize("xml")

Query Existing Metadata:

from ontolutils import query
from pivmetalib.pivmeta import PIVSoftware

# Find all PIV software in a file
software_list = query(cls=PIVSoftware, source='metadata.jsonld')

📄 License

This project is licensed under the MIT License - see the LICENSE.md file for details.

🙏 Acknowledgments

• Built on ontolutils for ontology handling
• Integrates with pivmeta ontology for PIV metadata standards
• Uses ontologies from schema.org, PROV, DCAT, and M4I