Population Medication Analysis¶
Runs a population-level medication analysis for a specified drug class. It fetches class info, enumerates member drugs (RxCUIs), and optionally gathers detailed RxNorm concept properties and RxTerms for each drug. Outputs two JSON strings: a high-level population analysis summary and per-drug details.
Usage¶
Use this node when you need an overview of all medications within a given drug class (e.g., MeSH, ATC, VA) and optional enrichment with RxNorm concept data and RxTerms. Typical workflow: supply a class identifier, choose whether to include detailed per-drug info, set a cap on the number of drugs to process, then pass the resulting JSON to downstream analytics, visualization, or reporting nodes.
Inputs¶
| Field | Required | Type | Description | Example |
|---|---|---|---|---|
| class_identifier | True | STRING | Identifier of the target drug class. This is passed to the RxClass lookups to discover member drugs (RxCUIs). | D007398 |
| class_type | True | STRING | Classification system of the identifier. Allowed values: MeSH, ATC, VA. Used for labeling/context in the output. | MeSH |
| include_drug_details | True | BOOLEAN | If true, fetches RxNorm concept information per drug (e.g., name and concept properties). | true |
| include_rxterms | True | BOOLEAN | If true, fetches RxTerms data per drug. | true |
| max_drugs | True | INT | Maximum number of RxCUIs to include in the analysis to limit processing and API calls. | 50 |
Outputs¶
| Field | Type | Description | Example |
|---|---|---|---|
| population_analysis | STRING | JSON string containing the compiled population-level summary, including class info, summary counts, timestamp, and the list of RxCUIs analyzed. | {"analysis_type":"Population-Level Medication Analysis","class_identifier":"D007398","class_type":"MeSH","population_summary":{"total_drugs":25,"class_name":"...","class_id":"...","analysis_timestamp":"2025-11-21T12:34:56"},"drug_list":["123","456"],"drug_details_summary":{"with_rxnorm_details":20,"with_rxterms":22,"errors":0},"analysis_ready":true} |
| drug_details | STRING | JSON string keyed by RxCUI with per-drug details (RxNorm name, properties, RxTerms) and a summary section. | {"total_drugs":25,"summary":{"with_rxnorm_details":20,"with_rxterms":22,"errors":0},"drugs":{"123":{"rxcui":"123","rxnorm_name":{"...": "..."},"properties":{"...": "..."},"rxterms":{"...": "..."}}}} |
| status | STRING | Human-readable status message indicating success or a specific error. | Successfully analyzed 25 drugs in class D007398 (MeSH) |
Important Notes¶
- Network/API dependency: This node relies on RxClass and RxNorm APIs via an internal RxNormAPI client. Connectivity or API issues will affect results.
- Input constraints: max_drugs limits how many RxCUIs are processed; larger values increase runtime and API usage.
- Optional enrichment: include_drug_details and include_rxterms control additional API calls per drug; enabling both provides richer data but can be slower.
- Error handling: On failures, outputs may return "{}" for population_analysis or drug_details and a status message describing the error.
- Class type usage: class_type is used for context/labeling in outputs; the class_identifier is what drives member lookup.
Troubleshooting¶
- Empty results or '{}' outputs: Verify the class_identifier is valid for the chosen classification system. Try a known ID and reduce max_drugs.
- API errors in status: Indicates upstream API or network issues. Retry later, reduce request volume, or disable optional enrichments to lessen load.
- Slow performance: Lower max_drugs or disable include_drug_details/include_rxterms. There is a small delay between per-drug calls to avoid overwhelming services.
- Unexpected class labeling: Ensure class_type matches the origin of the class_identifier for accurate context in the output.
- Downstream parsing errors: Remember outputs are JSON strings. Ensure your next step parses the string into structured data before use.