Metadata-Version: 2.2
Name: pivmetalib
Version: 2.0.0.0
Summary: A Python library for working with the pivmeta ontology.
Home-page: https://github.com/matthiasprobst/pivmetalib
Author: Matthias Probst
Author-email: matthias.probst@kit.edu
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Development Status :: 4 - Beta
Requires-Python: <3.13,>=3.8
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: rdflib>=7.0.0
Requires-Dist: appdirs>=1.4.4
Requires-Dist: simplejson>=3.19.2
Requires-Dist: python-dateutil>=2.9.0
Requires-Dist: requests>=2.32.3
Requires-Dist: ontolutils>=0.13.1
Provides-Extra: test
Requires-Dist: pytest>=8.3.2; extra == "test"
Requires-Dist: pytest-cov>=5.0.0; extra == "test"
Requires-Dist: pylint>=3.2.6; extra == "test"
Requires-Dist: pyyaml>=6.0.2; extra == "test"
Requires-Dist: xmltodict>=0.13.0; extra == "test"
Requires-Dist: ssnolib>=1.3.0.1; extra == "test"
Requires-Dist: h5rdmtoolbox>=1.6.0; extra == "test"
Provides-Extra: complete
Requires-Dist: pytest>=8.3.2; extra == "complete"
Requires-Dist: pytest-cov>=5.0.0; extra == "complete"
Requires-Dist: pylint>=3.2.6; extra == "complete"
Requires-Dist: pyyaml>=6.0.2; extra == "complete"
Requires-Dist: xmltodict>=0.13.0; extra == "complete"
Requires-Dist: ssnolib>=1.3.0.1; extra == "complete"
Requires-Dist: h5rdmtoolbox>=1.6.0; extra == "complete"

# pivmetalib

![Tests](https://github.com/matthiasprobst/pivmetalib/actions/workflows/tests.yml/badge.svg)
![DOCS](https://codecov.io/gh/matthiasprobst/pivmetalib/branch/main/graph/badge.svg)
![pyvers](https://img.shields.io/badge/python-3.8%20%7C%203.9%20%7C%203.10%20%7C%203.11%20%7C%203.12-blue)
![pivmeta](https://img.shields.io/badge/pivmeta-1.1.2-orange)

A Python library and high-level interface to work with the [pivmeta ontology](https://matthiasprobst.github.io/pivmeta/). 
It allows to describe PIV recordings, software, hardware and other related entities in a state-of-the-art and good
scientific practice compliant way.

The library depends on [ontolutils](https://ontology-utils.readthedocs.io/en/latest/), which provides the 
object-oriented interface to the ontology and the JSON-LD serialization.


## Usage

### Installation

The package is available on PyPI and can be installed via pip:
```bash
pip install pivmetalib
```

### Example of describing a PIV software:
It is very helpful to provide a description of the used PIV software together with the PIV recording. This can be done
using the `PIVSoftware` class from the `pivmeta` module. The following example shows how to describe the OpenPIV 
software. Put the resulting JSON-LD to your website, data repository or other places to make your data FAIR. 
Other users or software can then easily understand and use your data.

```python
from pivmetalib import pivmeta, prov

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 written in Python and Cython',
    software_version="0.26.0a0",
    has_documentation='https://openpiv.readthedocs.io/en/latest/',
)

from pprint import pprint

pprint(software.model_dump(exclude_none=True)
```

This will result in the following JSON-LD representation:

```bash
{
    "@context": {
        "@import": "https://raw.githubusercontent.com/matthiasprobst/pivmeta/main/pivmeta_context.jsonld"
    },
    "@graph": [
        {
            "@id": "https://local-domain.org/9c0696ff-7b0f-43a5-9d36-afca62f0f374",
            "@type": "prov:Organization",
            "foaf:name": "OpenPIV",
            "schema:url": "https://github.com/OpenPIV/openpiv-python"
        },
        {
            "@id": "https://local-domain.org/82675f3e-8887-4a76-a62c-cc1119857735",
            "@type": "Piv Software",
            "schema:author": {
                "@id": "https://local-domain.org/9c0696ff-7b0f-43a5-9d36-afca62f0f374"
            },
            "schema:description": "OpenPIV is an open source Particle Image Velocimetry analysis software written in Python and Cython",
            "schema:softwareVersion": "0.26.0a0",
            "sd:hasDocumentation": "https://openpiv.readthedocs.io/en/latest/"
        }
    ]
}
```


## Documentation and Usage

This library mainly implements the ontology in form of `pydantic` model classes. The *pivmeta* ontology uses other
ontologies and builds on top of them. Thus, some central classes from ontologies like *schema.org*, *prov*, *dcat* and
*m4i* are implemented, too.

Practical examples on how to use the library can be found in docs-folder (
e.g. [Describe a PIV recording](docs/Describe_a_PIV_recording.ipynb)).


## Contribution

Contributions are welcome. Please open an issue or a pull request.


