oc-ocdm 11.0.0

Object mapping library for manipulating RDF graphs that are compliant with the OpenCitations datamodel.

oc_ocdm

Documentation can be found here: https://oc-ocdm.readthedocs.io.

oc_ocdm is a Python ≥3.7 library that enables the user to import, produce, modify and export RDF data structures which are compliant with the OCDM v2.0.1 specification.

User's guide

This package can be simply installed with pip:

    pip install oc_ocdm

Please, have a look at the notebooks available here.

Developer's guide

First steps

1. Install Poetry:

    pip install poetry

2. Clone this repository:

    git clone https://github.com/opencitations/oc_ocdm
    cd ./oc_ocdm

3. Install all the dependencies:

    poetry install

4. Build the package (output dir: dist):

    poetry build

5. Globally install the package (alternatively, you can also install it inside a virtual-env, by providing the full path to the .tar.gz archive):

    pip install ./dist/oc_ocdm-<VERSION>.tar.gz

6. If everything went the right way, than you should be able to use the oc_ocdm library in your Python modules as follows:

    from oc_ocdm.graph import GraphSet
    from oc_ocdm.graph.entities.bibliographic import AgentRole
    # ...

How to run the tests

The project uses Virtuoso triplestore running in Docker for testing. Follow these steps to run the tests:

Prerequisites

• Docker installed and running
• All dependencies installed:

    poetry install

Basic test execution

On Linux/macOS:

    # Start the test database
    ./tests/start-test-database.sh
    
    # Run tests with coverage
    poetry run coverage run --rcfile=tests/coverage/.coveragerc
    
    # Stop the test database
    ./tests/stop-test-database.sh

On Windows (PowerShell):

    # Start the test database
    .\tests\start-test-database.ps1
    
    # Run tests with coverage
    poetry run coverage run --rcfile=tests/coverage/.coveragerc
    
    # Stop the test database
    .\tests\stop-test-database.ps1

How to manage the project using Poetry

See Poetry commands documentation.

AAA: when adding a non-dev dependency via poetry add, always remember to add that same dependency to the autodoc_mock_imports list in docs/source/conf.py (otherwise "Read the Docs" won't be able to compile the documentation correctly!).

How to publish the package onto Pypi

    poetry publish --build

Install dependencies needed for the documentation

    pip install Sphinx sphinx_rtd_theme

How to generate the documentation

    rm ./docs/source/modules/*
    sphinx-apidoc  -o ./docs/source/modules oc_ocdm *test*

How to build the documentation

---

Warning! In order to avoid getting the following WARNING: html_static_path entry '_static' does not exist, you'll need to manually create an empty _static folder with the command:

    mkdir docs/source/_static

---

1. Always remember to move inside the docs folder:

    cd docs

2. Use the Makefile provided to build the docs:
   • on Windows

         make.bat html
     

   • on Linux and MacOs

         make html
     

3. Open the build/html/index.html file with a web browser of your choice!

Citation

If you are using or extending oc_ocdm as part of a scientific publication, we would appreciate a citation of our article.

@inproceedings{persiani2022programming,
  title={{A} {P}rogramming {I}nterface for {C}reating {D}ata {A}ccording to the {SPAR} {O}ntologies and the {O}pen{C}itations {D}ata {M}odel},
  author={Persiani, Simone and Daquino, Marilena and Peroni, Silvio},
  booktitle={The Semantic Web: 19th International Conference, ESWC 2022, Hersonissos, Crete, Greece, May 29--June 2, 2022, Proceedings},
  pages={305--322},
  year={2022},
  organization={Springer}
}

Acknowledgements

This work has been funded by the project "Open Biomedical Citations in Context Corpus" (Wellcome Trust, Grant n. 214471/Z/18/Z) and the project "Wikipedia Citations in Wikidata" (Wikimedia Foundation, https://meta.wikimedia.org/wiki/Wikicite/grant/Wikipedia_Citations_in_Wikidata).

We would like to thank (in alphabetic order) Fabio Mariani (@FabioMariani), Arcangelo Massari (@arcangelo7), and Gabriele Pisciotta (@GabrielePisciotta) for the constructive feedback.