Make an API Call (Python SDK)
Important
Make sure you have gotten your API keys and configured your environment before trying to submit an API request.Step 1: Initialize the ScienceIO Client
To initialize the request, make sure you import the ScienceIO
library and create a scio
object:
from scienceio import ScienceIO
scio = ScienceIO()
You must use Python v3.7 or above.
Troubleshooting
If you are getting a ModuleNotFoundError, make sure you have installed the scienceio Python Package within the tool and/or notebook you are using. You may do this via the UI of some editors by searching for and adding the scienceio package, or by using thepip install scienceio
command within the notebook.Step 2: Submit the Request
All requests must be submitted using text.
Use the scio.structure()
method to submit a request to the structure
endpoint, which will ask the API to examine the query_text
, identify all healthcare concepts, and return the results (print(response)
) in JSON.
Click here to learn how to call a different endpoint.
# Replace the text with your query text. Single or double quotes are permitted.
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."
response = scio.structure(query_text)
print(response)
Note that your API keys will be passed to the API automatically because they were asked for when configuring your environment and/or running a query for the first time. You do not need to manually pass them in your code (exception: if you call the API again in a new Jupyter notebook, you may be asked to re-input your keys). You can find or edit your keys in ~/.scienceio/config
.
Step 3: Examine the API Response
The response from the API is in JSON, and includes a number of key:value pairs that hold the pieces of healthcare information found in the query_text
. If you are working in a Jupyter notebook, you can add the following code to make the results easier to read.
import json
print(json.dumps(response, indent=2))
For more information about each key:value pair in the JSON response (shown below), see JSON Schema: Structure.
{
"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.",
"spans": [
{
"concept_id": "UMLS:C0002736",
"concept_name": "Amyotrophic Lateral Sclerosis",
"concept_type": "Medical Conditions",
"pos_end": 3,
"pos_start": 0,
"score_id": 0.9997076392173767,
"score_type": 0.999858021736145,
"text": "ALS"
},
{
"concept_id": "UMLS:C0002736",
"concept_name": "Amyotrophic Lateral Sclerosis",
"concept_type": "Medical Conditions",
"pos_end": 40,
"pos_start": 20,
"score_id": 0.6796196103096008,
"score_type": 0.9957892298698425,
"text": "Lou Gehrig's disease"
},
{
"concept_id": "UMLS:C0004795",
"concept_name": "Baseball Game",
"concept_type": "Context",
"pos_end": 60,
"pos_start": 52,
"score_id": 0.9998717308044434,
"score_type": 0.9998181462287903,
"text": "baseball"
},
{
"concept_id": "UMLS:C0031831",
"concept_name": "Physicians",
"concept_type": "Context",
"pos_end": 102,
"pos_start": 95,
"score_id": 0.9998661279678345,
"score_type": 0.9999226331710815,
"text": "Doctors"
},
{
"concept_id": "UMLS:C0002736",
"concept_name": "Amyotrophic Lateral Sclerosis",
"concept_type": "Medical Conditions",
"pos_end": 130,
"pos_start": 127,
"score_id": 0.9996334314346313,
"score_type": 0.999842643737793,
"text": "ALS"
}
]
}
Step 4: Use Pandas to Explore the Response (Optional)
You can perform further analysis of the JSON response by using pandas to create a DataFrame. ScienceIO recommends using pandas to get the most out of your data.
1. Import Package and Create a DataFrame
First, import pandas
under the pd alias, and load your JSON response to a DataFrame using the json_normalize operation.
# Import required package
import pandas as pd
# Load JSON response to df
df = pd.json_normalize(response['spans'])
df.head()
The result looks like this:
2. Decide How to Explore
Next, decide how you want to filter your results. Here are two additional code examples that can be used after you load your JSON response to a DataFrame.
Example 1: Filter results to only include medical conditions:
# Subset the df to only medical conditions
filtered_results = df[df["concept_type"]=="Medical Conditions"]
filtered_results
The result looks like this:
Example 2: Create a count of each unique medical condition:
# Create a count of each unique medical condition
filtered_results["concept_name"].value_counts()
The result looks like this:
Click here to learn more about using pandas.
Feedback
Was this page helpful?
Great! If you ever have questions or want to provide feedback, send us an email.
Bummer. We hate when we miss the mark. If you have suggestions for improvements or other general comments, send us an email.