Structure

When you submit text to the ScienceIO API via this endpoint, our AI analyzes the query text, identifies all text that refers to healthcare concepts, and directly maps each piece of text to the appropriate concept using an array of dictionaries under spans. Each dictionary uses keys to map the healthcare information found in the text.

How to Access the Endpoint

Python SDK

Use the scio.structure() method to submit the request, which will ask the API to examine query_text, identify all healthcare concepts, and return the results.

#initialize the ScienceIO client

from scienceio import ScienceIO
scio = ScienceIO()

#call the endpoint

query_text = "ALS is often called Lou Gehrig's disease, after the baseball player who was diagnosed with it. Doctors usually do not know why ALS occurs."
#specify the structure endpoint here
response = scio.structure(query_text)
print(response)

Go to Make an API Call (Python SDK) for detailed instructions on using the SDK to make a call to this endpoint.

HTTP

Go to Make an API Call (HTTP) for manual configuration instructions.

Sample Response

In the example below, the query text included four pieces of healthcare information ("patient," "CHF," "renal failure," and "statins"), so the API returned four dictionaries to map each one.

{
  "text": "The patient was diagnosed with CHF and renal failure and administered statins.",
  "spans": [
    {
      "concept_id": "UMLS:C0086418",
      "concept_name": "Homo sapiens",
      "concept_type": "Species & Viruses",
      "pos_end": 11,
      "pos_start": 4,
      "score_id": 0.9999945163726807,
      "score_type": 0.9999994039535522,
      "text": "patient"
    },
    {
      "concept_id": "UMLS:C0018801",
      "concept_name": "Heart failure",
      "concept_type": "Medical Conditions",
      "pos_end": 34,
      "pos_start": 31,
      "score_id": 0.997938334941864,
      "score_type": 0.9998775720596313,
      "text": "CHF"
    },
    {
      "concept_id": "UMLS:C0035078",
      "concept_name": "Kidney Failure",
      "concept_type": "Medical Conditions",
      "pos_end": 52,
      "pos_start": 39,
      "score_id": 0.9999425411224365,
      "score_type": 0.9999667406082153,
      "text": "renal failure"
    },
    {
      "concept_id": "UMLS:C0360714",
      "concept_name": "Hydroxymethylglutaryl-CoA Reductase Inhibitors",
      "concept_type": "Chemicals & Drugs",
      "pos_end": 77,
      "pos_start": 70,
      "score_id": 0.9997879862785339,
      "score_type": 0.9999738931655884,
      "text": "statins"
    }
  ]
}

📘

Note

This example was created using the Python SDK. You may also call the structure model using POST. See Make an API Call (HTTP) for more information.

A Closer Look at Keys

The response includes 7 keys with a corresponding value.

Text

A piece of text from the request that is recognized as healthcare information. In this example, "CHF" was recognized as healthcare information that needed to be mapped to an identifier.

"text": "CHF",

Concept ID

The unique identifier for the healthcare information that text is referring to. In this example, "CHF" was mapped to UMLS:C0018801.

Note: The backbone of the API's vocabulary is the UMLS, or Unified Medical Language System, which is a set of files and software that enables interoperability between computer systems. Most concept IDs will come from the UMLS as the primary ontology. However, we also use other ontologies in this field.

"concept_id": "UMLS:C0018801",

Concept Name

The standard reference name for the concept_id, which is provided to increase readability without having to look up the unique identifier. In this example, UMLS:C0018801 has a concept_name of "Heart failure".

"concept_name": "Heart failure",

Concept Type

The broad category of information that the concept_id belongs to. In this example, UMLS:C0018801 has a concept_type of "Medical Conditions".

Note: These categories were created by ScienceIO to enable high-level views of data. See Concept Types for more information.

"concept_type": "Medical Conditions",

Position Start and End

The precise location of the healthcare information in the original request. In this example, "CHF" appears from the 31st to 34th indices in the query text.

"pos_start": 31,
"pos_end": 34,

Score ID

The AI's confidence that text was properly mapped to concept_id. In this example, the score_id is 0.9979, which means ScienceIO is extremely confident that "CHF" best refers to UMLS:C0018801 (Heart failure).

Note: This score ranges from 0 to 1 (no confidence to full confidence); a score of 1.0 is a perfect match.

"score_id": 0.9979

Score Type

The AI's confidence that text was properly mapped to concept_type. In this example, the score_type is 0.9998, which means ScienceIO is extremely confident that "CHF" best refers to "Medical Conditions".

Note: This score ranges from 0 to 1 (no confidence to full confidence); a score of 1.0 is a perfect match.

"score_type": 0.9998