scriptEncounter
Query patient prescription claims that meet the specified criterion with line item detail.
Get Started with scriptEncounter
If you have already setup CareQuery, run the below code to get started with your first scriptEncounter query.
Example:
Childbearing-aged females given progesterone prescriptions in March of 2023 in the mountain west.
# 1) import
from care_query.care_query import CareQuery
# 2) instantiate and connect
cq = CareQuery(email = "your-email",
token = "your-api-token",
sftp_key = "path/to/your/company.PEM")
# 3) build query
query_name = cq.scriptEncounter(pharm_class = ["progesterone [epc]",
"progesterone agonist/antagonist [epc]"],
gender = "F",
age_min = 15,
age_max = 45,
state = "KS",
min_date = "2023-03-01",
max_date = "2023-04-01",
alias = "kansas_progesterone_scripts", # optional argument to add sftp_path prefix
limit = 10000) # False returns all rows
# 4) submit query, data will return to SFTP endpoint
# could also run .sample() to return the first 1k rows or .execute() to get a size estimate
result_object = query_name.execute()
# 5) check query status
# user will be sent an email upon submission and completion, check query status along the way
query_name.queryStatus()
# 6) upon successful completion of query, read data directly into pandas environment
result_data = query_name.sftpToPandas()
Query Parameters
The following a parameters are available within the scriptEncounter query, including details on the parameter values.
| parameter | description | options |
|---|---|---|
min_date | Lower threshold date within the date range of interest, observational start date | Date String |
max_date | Upper threshold date within the date range of interest, observational end date | Date String |
gender | Patient gender within the population of interest | M,F or ['M','F'] |
age_min | Minimum patient age identified within the population of interest | 0 to 120 |
age_max | Maximum patient age identified within the population of interest | 0 to 120 |
ndc | FDA National Drug Code version 11 standardized code for a dispensed drug | Any Valid National Drug Code (Please see SCRIPT_DETAIL_TABLE or Unformatted NDC11 for full list of options) |
pharm_class | Classifications of a drug product based on its therapeutic action, or how it works in the body | values available |
substance | The active ingredient in a drug product | values available |
marketing_category | Classification of a drug product based on its regulatory status and how it is marketed | values available |
taxonomy_code | Taxonomy of the organization or individual provider, 10-digit code that used to identify the type, classification, and area of specialization of an individual or organizational healthcare provider | values available |
specialty | Specialty of the organization or individual provider(s), specific focus of a provider by patient population, disease, skill or philosophy | values available |
specialty_category | Specialty category of the organization or individual provider(s), broad focus of a provider by patient population, disease, skill or philosophy | values available |
subspecialty | Specialty subcategory of the organization or individual provider(s), hyper-specific focus of a provider by patient population, disease, skill or philosophy | values available |
npi | National Provider Identifier (NPI) of individual and/or organizational provider(s) that appear on the encounter. | Any Valid National Provider Identifier (NPI) |
state | US State residence of the query patient population | values available |
division | Nine distinct US State groupings as defined by the US Census Bureau | values available |
region | Four major US State groupings as defined by the US Census Bureau | values available |
metro | Metropolitan and micropolitan statistical areas according to the US Census Bureau | values available |
short_zip | First three digits the zip code of the query patient population specified | First 3 digits of zip code(s) |
limit | Number of rows returned in the data request | Integer or False |
show | Binary indicator as to whether you'd like query to be printed for review upon it's creation | True or False |
Query Speed
scriptEncounter - depending on the complexity and size of the query, most queries will return results within 30 seconds to 3 minutes.
Median Query Speed: 1 minute and 30 seconds
Query Return Data
The scriptEncounter query returns the SCRIPT_TABLE for all encounters that meet the criterion specified within the query.
The SCRIPT_TABLE provides prescription claim with comprehensive drug and provider details, across entire longitudinal journeys.
| feature | description | example |
|---|---|---|
| journey_id | Randomly generated identifier unique to each longitudinal patient journey. | 355ed5199ebed017821c7faa62965a61 |
| script_id | Randomly generated identifier unique to each prescription claim. | 9318831e2ce3f30a83b1317b4d02ebfd |
| group_id | Randomly generated identifier unique to each payor plan corresponding to the prescription written. | 315cb4170e73bed429a86e3dbb4e95a |
| script_date | Date the prescription was written | 2022-01-21 |
| service_date | Date that the prescription was filled, services rendered, or the payer began coverage following Part A expiration in a long-term care setting | 2019-02-25 |
| patient_state | US State residence of the patient on each encounter | AZ |
| patient_short_zip | First three digits of the patient's zip code | 801 |
| patient_age | Age (within 5 years) of the patient at the moment of each encounter. | 62 |
| patient_gender | Gender/Sex of the patient | M |
| hcp_npi | National Provider Identifier (NPI) of the individual that wrote the prescription for the patient. | 1003878000 |
| hcp_taxonomy | Primary taxonomy code of the individual provider who wrote the prescription. | 207Q00000X |
| hcp_specialty | Primary specialty of the individual provider provider wrote the prescription. | family medicine - general |
| hco_npi | National Provider Identifier (NPI) of the organization that fulfilled the prescription | 1063001238 |
| ndc | FDA National Drug Code version 11 standardized code for a dispensed drug | 68645054154 |
| proprietary_name | Unique brand name of a drug product as assigned by the drug manufacturer | glimepiride |
| refills | Maximum number of refills authorized | 1 |
| quantity_prescribed | Quantity of drug units prescribed | 0 |
| quantity_dispensed | Quantity of drug units dispensed | 30 |
| fill_number | Refill number for the current SCRIPT_ID | 1 |
| days_supply | Estimated number of days the dispensed drugs will last | 30 |
| unit_of_measure | Units of measure for the quantity_dispensed | EA |
| submitted_cost | Pharmacy submitted cost of the claim | $46.00 |
| patient_pay | Patient cost responsibility as determined by payor | $5.90 |
| copay_insurance | Patient cost responsibility as copay or coinsurance | $0.00 |
| plan_pay | Payor cost responsibility | $1.50 |
Advanced Query Logic & Recipes
As one thinks about what the healthcare encounter's they'd like returned in a query...the diagnosis, procedure, location, time and specialty criterion...things can get quite complex.
scriptEncounter gives users categorical groupings for ease of use, as well as SQL-like capabilities to tactfully specify AND and OR logic, right within the CareQuery API!
Please reference the following resources to better understand how to create rockstar queries!
Updated 11 months ago