Skip to content
EBISPOTPublic

About

A SSSOM compliant implementation of OxO that is backwards compatible with OxO version 1

Resources

Stars

2 stars

Watchers

3 watching

Forks

Latest commit

 

History

722 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

OxO2

A SSSOM compliant implementation of OxO that is backwards compatible with OxO version 1

User documentation

docs/user/ui/oxo2-user-interface.html is a standalone guide to the web interface — searching, reading results, how mappings are ranked, and the rough edges. A PDF is generated from it. Open either straight from disk; no build step, no server.

Releases

Software releases are cut by merging a pull request into stable; the push tags vX.Y.Z, publishes a GitHub release with a Zenodo DOI, builds versioned multi-platform images and then moves the :stable image tags. See docs/releases.md. Mapping data releases (docs/hpc-data-release.md) and deployments are separate actions.

API documentation

The backend publishes an OpenAPI 3 description of its REST API. Once the backend is running (http://localhost:8081 in the setups below), the interactive Swagger UI is available at http://localhost:8081/swagger-ui.html and the raw OpenAPI spec at http://localhost:8081/v3/api-docs.

GET /api/v2/mappings/{mappingId}/support?page=0&size=20 returns all records for the selected mapping's subject, predicate, modifier and object, including the selected record. It ignores search filters and returns a mappings page plus group-wide justificationMethodCount and assertedSourceCount. Pages are zero-based; size is 1–100. Asserted sources count distinct mapping sets directly asserting that statement, not inference premises or independent evidence.

Default search order puts more distinct direct asserted source sets first: three above two, two above one, and one above zero. The existing relevance and provenance score breaks ties. Repeated records from one set and extra justification methods do not increase the source count. Explicit sorting replaces this default order. Swagger documents the full response and error contract; ADR-0054 records the design.

Running OxO2 using Docker

Prerequisites

  1. Ensure docker is installed in your environment.

Environment variables

  1. Set OXO2_CONFIG environment variable - It should point to the OxO2 config file. This is how OxO2 knows which SSSOM mappings to load. For an example config file see the oxo-config.json in the root of the OxO2 code base. Copy your desired configuration file into the root directory of OXO2. E.g. if your configuration file is my_oxo2_config.json, set OXO2_CONFIG=./my_oxo2_config.json by running export OXO2_CONFIG=./my_oxo2_config.json.

Steps

  1. To run OxO2 using docker, run docker compose up. This will start Solr, the OxO2 backend and OxO2 frontend. The frontend will be available at http://localhost:8080, the backend at http://localhost:8081 and Solr at http://localhost:8983.
  2. To stop OxO2 run docker compose down.

Upgrading from an earlier OxO2 release

All OxO2 containers now run as non-root users (oxo, UID 8389, for dataload/backend; solr, UID 8389, for solr; node, UID 1000, for frontend). If you are upgrading from a release where the dataload container ran as root, the existing Docker named volumes (data, logs, solr-data) are still root-owned and the non-root dataload container will not be able to write to them. Recreate the volumes once:

docker compose down -v
docker compose up

Running OxO2 locally in Kubernetes using Minikube

Prerequisites

  1. Ensure you have a kubernetes cluster available. E.g. for a local k8s cluster using minikube run minikube start --driver=docker.
  2. Ensure you have helm installed.

Environment variables

  1. Ensure that you have a data release such that have the complete OxO2 available at a $SOLR_HOME.

Mount your data into minikube

  1. Mount into minikube: minikube mount --port=39000 $SOLR_HOME:/mnt/oxo/solr-data.

Note: You may need to allow port 39000 through firewall. If so, run: sudo ufw allow 39000/tcp.

Deployment

  1. From the root directory run:
helm install oxo2 ./k8chart-local/oxo2 -n ontotools --create-namespace
  1. To access locally run:
kubectl port-forward deployment/oxo2-frontend 8080:8080 -n ontotools
kubectl port-forward deployment/oxo2-backend 8081:8081 -n ontotools
kubectl port-forward deployment/oxo2-solr 8983:8983 -n ontotools

and the point your browser to http://localhost:8080. The OxO2 backend will be accessible at http://localhost:8081/ and solr at http://localhost:8983.

To undeploy

  1. Run: helm uninstall oxo2 -n ontotools.

Running OxO2 locally from the commandline.

Prerequisites

Ensure the following software is installed and available on the user path.

  1. Java 25
  2. Maven 3.x
  3. Git
  4. Solr 9.x - This is the datastore for OxO2. Ensure SOLR_SCRIPT is set to /bin dir SOLR_HOME is set to /server/solr dir of your Solr installation.
  5. Nemo - Nemo is the rules engine used in OxO2. Download the latest version from Nemo latest or build from source following instructions here. To check your Nemo installation, run nmo --help. Ensure that nmo is available on the path.
  6. Optionally you could use Nextflow for parallelising the OxO2 dataload. Nextflow can be installed using curl -s https://get.nextflow.io | bash. Make sure to add it to your path.

Environment variables

Define the following environment variables:

  1. OXO2_DATA - This is where SSSOM files will be downloaded to and where any output of the OxO2 dataload will be written.
  2. OXO2_CONFIG - Points to the OxO2 config file. This is how OxO2 knows which SSSOM mappings to load. For an example config file see the oxo-config.json in the root of the OxO2 source code directory. NOTE: This must be the absolute path to the file.
  3. SOLR_SCRIPT - This should point to the bin directory of your Solr installation.
  4. SOLR_HOME - This should point to the root of your Solr data directory.
  5. SOLR_HEAP - The Solr JVM heap. Use at least 4g for the full OxO2 index; Solr ignores JAVA_OPTS and otherwise defaults to 512m.
  6. OXO2_SOLR_HOST - This is the URL to your Solr installation.
  7. NEXTFLOW_DIR - If you want to parallelise the OxO2 dataload using Nextflow, you need to specify where it can write interm results.

Here is an example script for setting environment variables:

export SOLR_SCRIPT=/home/myhome/solr-10.0.0/bin
export SOLR_HOME=/home/myhome/oxo2-data/solr
export SOLR_HEAP=4g
export PATH=$PATH:/home/myhome/nemo
export OXO2_DATA=/home/myhome/oxo2-data/dataload
export OXO2_CONFIG=/home/myhome/oxo2/my_oxo2_config.json
export OXO2_SOLR_HOST=http://localhost:8983/solr
export NEXTFLOW_DIR=/home/myhome/nextflow

Steps

  1. Checkout OxO2: git clone git@github.com:EBISPOT/oxo2.git and change to OxO2 source directory.
  2. To build, run: mvn clean install
  3. Change to dataload directory: cd ./oxo2-dataload
  4. Run OxO2 dataload: ./loadData.nextflow (Nextflow is required). It lays down the Solr config itself and stops Solr again when it finishes.
  5. Return to OxO2 root dir: cd ..
  6. Start Solr: ./startSolr.sh — always use this rather than calling solr start directly, since Solr 10 defaults to SolrCloud mode, in which OxO2's cores cannot load.
  7. Run OxO backend: ./startBackend.sh
  8. To build and run frontend:
    1. Change directory to frontend: cd oxo2-frontend
    2. Build frontend: npm install
    3. Start frontend: npm run dev
    4. Access frontend from browser at: http://localhost:8080/
    5. Backend is accessible at: http://localhost:8081.

To stop the local Solr, run ./stopSolr.sh from the OxO2 root with the same environment used to start it. It stops only the configured port (SOLR_PORT, then the port in SOLR_URL, defaulting to 8983) and leaves the index data in place. In a worktree, load its .envrc with direnv or source oxo2-env.sh first so the correct instance is selected.

About

A SSSOM compliant implementation of OxO that is backwards compatible with OxO version 1

Resources

Stars

2 stars

Watchers

3 watching

Forks

Releases

Packages

Used by

Contributors

Languages