Basic Client

This document provides instructions on using the included basic client, emtellipro-client for submitting documents for processing and saving results. This client only accepts files as the input type and just writes the raw emtelliPro output into an output file.

First, ensure you’ve installed the SDK package: Installation

Next, read the help output that the client can create for its various commands, e.g.:

emtellipro-client --help

This will show you that there are four commands you can use when running the emtellipro-client:

submit - for submitting a document for processing

continue - for continuing an interrupted job (if you created a state file)

debug - for dumping out a state file to see debugging info from a processing run (if you created a state file)

get-user - confirming that a pair of API keys are valid

You can find out more information about each of these commands by running them followed by the --help option, e.g.:

emtellipro-client submit --help

Confirming API Access

Before you get started, ensure that you have your public and private keys for access to the API. If for some reason you don’t, contact us at info@emtelligent.com to get set up.

The next step is ensuring that your API keys are set up and working – to make sure you can use your API keys and can connect to the server, the quickest way is to use the provided example client to try and retrieve your user information:

emtellipro-client \
    get-user \
    --access-key ACCESS_KEY \
    --secret-key SECRET_KEY \
    --server https://api.emtelligent.com:50001

If successful and your access is set up, this command will print out your username with a response like:

User with username: test_user

Submitting files for processing

The command-line client also lets you submit files for processing and saving the results in JSONL format to OUTPUTFILE.

emtellipro-client \
    submit \
    --access-key ACCESS_KEY \
    --secret-key SECRET_KEY \
    --server https://API_URL \
    --state-file STATE_FILE_NAME
    --category DOC_CATEGORY \
    --subcategory DOC_SUBCATEGORY \
    --features FEATURE1,FEATURE2,FEATURE3... \
    --output OUTPUTFILE \
    INPUTFILE

We have provided a sample CT scan report for test processing in the example-data directory. An example of using the simple client for processing is below:

emtellipro-client \
    submit \
    --access-key 9988776655... \
    --secret-key 1122334455... \
    --server https://api.emtelligent.com:50001 \
    --state-file ./sample_state_file.log
    --category Radiology \
    --subcategory CT \
    --features text,emtelligent-ontology,snomed-ontology,radlex-ontology,experiencer-relations,entity-polarity,entity-uncertainty \
    --output sample_output.jsonl \
    example-data/sample_ct_report.txt

If this is successful, you’ll see output that looks like this (when processing is complete):

Waiting for processing results  [####################################]  100%

And you should have a file in your directory called sample_output.jsonl. It’s in JSONL format, meaning each line is a separate JSON object. A quick way to prettyprint this for review is:

python -m json.tool <( head -1 ./sample_output.jsonl) | more

Which will then show you the structured data output from the emtelliPro API of everything that was converted from the input file:

[
    {
        "relations": {
            "experiencers": [
                {
                    "attributes": {
                        "polarity": "asserted"
                    },
                    "label": "R0",
                    "args": [
                        {
                            "ref": "Epatient",
                            "text": [
...

Debugging

In general, you should probably always submit jobs using the --state-file option. This creates a state file that contains information about your job in case something goes wrong, and will allow you to resume the job if it is interrupted for some reason (e.g. a network outage).

The state files are not in a human-readable format, so to dump them out, you need to use the debug command with emtellipro-client, e.g.:

emtellipro-client debug ./sample_state_file.log

This will output some data similar to the below showing you information about your processing submission:

{
 'docs_done': 1,
 'document_type': 'plain',
 'features': None,
 'num_docs': 1,
 'output': '/home/username/emtellipro-python-sdk/sample_output.jsonl',
 'result_format': 'emtellipro-json-2',
 'state_file': '/home/username/emtellipro-python-sdk/sample_state_file.log',
 'task_ids': ['4ad6bd67-5106-49ce-a408-454979926101']
}

Submitting a single section for processing

An alternative to reading full documents is to process only certain sections from a full document. For example, you might want to only process the FINDINGS section from a collection of Radiology/CT reports. The command-line client also lets you submit individual portions of a full report for processing and saving the results in JSONL format to OUTPUTFILE.

emtellipro-client \
    submit \
    --access-key ACCESS_KEY \
    --secret-key SECRET_KEY \
    --server https://API_URL \
    --category DOC_CATEGORY \
    --subcategory DOC_SUBCATEGORY \
    --section-label SECTION_LABELS \
    --output OUTPUTFILE \
    INPUTFILE

The additional option --section-label is used to provide a section label. You can provide nested section information as well by usign :: to separate the nested section names, e.g. "FINDINGS::LUNG BASES AND HEART APEX" or FINDINGS::LIVER.

A sample section input file is provided in example-data/sample_ct_findings_section.txt which you can use to test submission of a single section in the command-line client.

The example discussed above used a single section but you can use this same option to submit a fragment of a report with multiple sub-sections. The only difference from a submit command without the --section-label is that the provided fragment of text is assumed to exist in a section with the provided section label. For instance, you could provide the FINDINGS section which contains multiple sub-sections like LIVER: and GALLBLADDER: and PANCREAS:.

Next steps

Before going further, it’s a good time to check out some of the emtelliPro documentation about Submitting Documents and Understanding the emtelliPro Output.

But if you already understand the ins and outs of emtelliPro, and want to move on to a more advanced client example, check out Database Client for a working example of our database client, emtellipro-db-client that can take files or data from a database for processing and saves the output to a set of database tables that it can create.