An example implementation of the NLP Sandbox Date Annotator.

• Implements the NLP Sandbox Date Annotator OpenAPI specification
• Annotates date strings in clinical notes using simple regular expressions

NLP Sandbox API implemented:

The command below starts the Date Annotator locally.

docker-compose up

We recommend using a Conda environment to install and run the Date Annotator.

conda create --name nlp-sandbox-date-annotator-example python=3.8.5
conda activate nlp-sandbox-date-annotator-example

Install and start the Date Annotator.

cd server/
pip install -r requirements.txt
cd server && python -m openapi_server

When running, the Date Annotator provides a web interface (http://localhost:8080/api/v1/ui/) that you can use to explore the input, output and actions available.

Requirements:

• The NLP Sandbox requires NLP Tools to be dockerized
• The dockerized tool must be standalone and not depends on access to the Internet. This requirement contributes to make the tool more reproducible.

This section describes how you can start developing your own Date Annotator that you can then submit for evaluation to the NLP Sandbox.

• Node JS
• Java (required by OpenAPITools/openapi-generator)

One option is to create a GitHub repository based on this template repository if you plan to write your code in Python. This repository comes with a GitHub workflow that will help you implementing good practices and notify you when a new version of the OpenAPI specification for this NLP Tool is available. The GitHub workfow also includes a job to automatically submit your Date Annotator to the NLP Sandbox for evaluation.

Alternatively, follow the steps listed below to generate an initial implementation of the Date Annotator using one of the many languages and framework supported by OpenAPITools/openapi-generator.

Start by downloading the latest version of the NLP Sandbox Date Annotator OpenAPI specification and save this file to the root folder of your project.

curl -f -O https://sage-bionetworks.github.io/nlp-sandbox-schemas/date-annotator/latest/openapi.yaml

Create the file package.json with this content:

{
    "name": "awesome-date-annotator",
    "version": "1.0.0",
    "license": "Apache-2.0",
    "devDependencies": {
        "@openapitools/openapi-generator-cli": "^1.0.18-4.3.1"
    },
    "scripts": {
        "test": "tox"
    }
}

Install the dependencies listed in package.json

npm install

Display help information about openapi-generator

./node_modules/.bin/openapi-generator --help

Identify the server generator that you want to use from this list

./node_modules/.bin/openapi-generator list

Generate the server codebase using the selected generator (here python-flask)

./node_modules/.bin/openapi-generator \
    generate -i openapi.yaml -g python-flask -o server

That's it! You can now start the Data Annotator server using the instructions given in the section Running using Python.

Generate the initial server stub from the OpenAPI specification

mkdir server
./node_modules/.bin/openapi-generator-cli \
    generate -i openapi.yaml -g spring -o server

Build and start the server with Maven

cd server
mvn package
java -jar target/openapi-spring-0.1.6.jar

The API documentation UI is now available at http://localhost:8080.