open_fda_drug_label

Submodules

• open_fda_drug_label.api
• open_fda_drug_label.drug
• open_fda_drug_label.open_fda_drug_label
• open_fda_drug_label.shelf

Attributes

__version__

Classes

Drug_Label_Client	OVERVIEW:
Drug	OVERVIEW:
Shelf	OVERVIEW:

Functions

make_drugs(api_key, field_list, criteria_list[, ...])

OVERVIEW:

Package Contents

open_fda_drug_label.__version__

open_fda_drug_label.make_drugs(api_key, field_list: list, criteria_list: list, exact: bool = False, limit: int = 1)

OVERVIEW:

Function designed to streamline new drug construction. Takes in user’s API key, list of desired search fields, list of specific criteria for each field, whether exact match is to be used, and limit of search results

Parameters:

• field_list (list) – list of strings containing appropriate fields for drug search of openFDA

• criteria_list (list) – list of strings containing specific search terms for inputted fields

• exact (bool) – checking if exact match should be used or not

• limit (int) – number of drugs that should be enabled in a drug search

RETURN VALUE:

drugs (list): list of drug(s) that were generated by this function

USAGE EXAMPLE:

>>> make_drugs(api_key, ["brand_name"],["Advil"],exact=True, limit=3)
>>> # above code builds list of 3 drugs named exactly "Advil"

class open_fda_drug_label.Drug_Label_Client(api_key: str)

OVERVIEW:

The Label Client is an API client class that allows an individual to engage directly with the openFDA Drug/Label API after loading in their API key. Users can use generic_search and search_request in tandem to expedite search-term specific API calls, or use manual_request for non-Drug/label search-specific queries of the broader openFDA API environment.

ATTRIBUTES

api_key (str): OpenFDA API key loaded in by user base_url (str): Base URL for OpenFDA endpoint (shortcut functions) session (requests.Session()): Universal HTTP sesh for API requests

USAGE EXAMPLE:

>>> # User function loads in API key as api_key
>>> client = Drug_Label_Client(api_key)
>>> advil_items = generic_search("brand_name", "Advil")
>>> advil_json = search_request(advil_items, limit=1)
>>> print(advil_json) # prints raw complete json for shortcut query

api_key

base_url = 'https://api.fda.gov/drug/label.json'

session

search_request(search_items, limit: int = 1)

OVERVIEW:

Executes a search based on an inputted list of search_items which contains a list of searches built by generic_search. Returns a raw json with the number of searches equal to limit.

Parameters:

• search_items (list) – list of fields generated by generic_search

• limit (int) – defines the number of total drugs contained in json

RETURN VALUE:

returns response.json(), raw json format of openFDA HTTPS request

USAGE EXAMPLE:

>>> client = Drug_Label_Client(api_key)
>>> client.search_request([generic_search("brand_name","Advil")])
>>> # above gives json format of first item search for "Advil"

generic_search(parameter, name, exact=False)

OVERVIEW:

Generates a generic_search string for input into the search_request function. Takes in a parameter (of any drug) and a particular name for the parameter to search for. For example, searching by parameter “brand_name” and name “Advil” yields all drugs with “Advil” in the “brand_name” field. Exact allows for exact string matching in the search field, and defaults to false.

Multiple generic_search functions can be combined using +AND+ and this is the reason for including all generic_search items in a list when inputting into search_request.

Parameters:

• parameter (str) – field search function is being performed on

• name (str) – string to match parameter search function to

• exact (Bool) – designates whether exact match is required

RETURN VALUE:

search_item (str): string formatted for link insertion

USAGE EXAMPLE:

>>> client = Drug_Label_Client(api_key)
>>> client.generic_search("brand_name","Advil")
>>> # above returns list of drugs w/ "brand_name" containing "Advil"

manual_request(url)

OVERVIEW:

Executes a manual data pull request using a user-provided url.

Parameters:

url (str) – string of user-inputted url.

RETURN VALUE:

response.json() => json response if valid url is enterred.

USAGE EXAMPLE:

>>> client = Drug_Label_Client(api_key)
>>> url = # [user inputted string]
>>> client.manual_request(url)

class open_fda_drug_label.Drug(meta: dict, result: dict)

OVERVIEW:

Drug object is the primary object used to engage with drugs in the openFDA drug/label dataset after retrieved from API call. Drugs are generated by inputting the “meta” and “results” sections of the raw json return, and can be generated with make_drug in our final package implementation. Drugs allow users to call a number of different functions to collect individual parameter values from the openFDA dataset or to provide high level overviews, risk scores, or comprehensive data structure with all fields from the raw json file. This class is designed to make accessing information about a particular drug extremely easy based on the raw json file.

ATTRIBUTES

raw: core json output for results of an individual query about a drug meta: meta information from a query used to produce this individual drug openfda: specific openfda subsection of the json output for this drug

USAGE EXAMPLE:

>>> # User function loads in API key as api_key
>>> client = Drug_Label_Client(api_key)
>>> advil_items = generic_search("brand_name", "Advil")
>>> advil_json = search_request(advil_items, limit=1)
>>> advil_drug = Drug(advil_json["meta"], advil_json["results"][0])
>>> advil_drug.drug_overview() # returns overall dict about drug stats

raw

meta

openfda

raw_drug()

OVERVIEW:

Returns the raw json of the results without any processing for interested parties to manipulate with their own functions.

Parameters:

None – simply takes the object and returns an attribute

RETURN VALUE:

raw (dict): returns the json format of the results section

USAGE EXAMPLE:

>>> Advil.raw_drug() # returns raw value of self.raw

get_name()

OVERVIEW:

Returns the drug’s name from the openfda subsection of results by checking for name in “brand_name.” If not available in that field, checks backups of “generic_name” and “substance_name” to try and locate an appropriate name. Returns None if not possible.

Parameters:

None – simply takes the object and returns an attribute

RETURN VALUE:

name (str/None): returns the name of a given drug if available

USAGE EXAMPLE:

>>> Advil.get_name() # returns full name of advil drug if available

get_parameter(parameter: str)

OVERVIEW:

Returns (if available) the field for a provided parameter of the drug in whatever contained format is present. If field is not available, returns None as a value to the user. Rejects name parameters and asks user to use get_name function shown above.

Parameters:

parameter (str) – field we want to extract value of for Drug

RETURN VALUE:

value (str/list/None): value contained in dict for parameter # if parameter contains a list, returns the first element

USAGE EXAMPLE:

>>> Advil.get_parameter("ingredients") # returns advil ingredients

drug_overview()

OVERVIEW:

Function that provides a dictionary with a high level overview of descriptive statistics on the drug object. Includes drug name, universal production code, manufacturer name, product type, route, description, and risk score, which measures number of fields with high risks that are actually populated using risk_score function below.

Parameters:

None

RETURN VALUE:

drug_info (dict): contains keys for overview parameters and values

name (str): name of drug upc (str): universal product code of drug manufacturer name (str): man. who made the drug product type (str): kind of product sold route (str): how to take this drug (e.g. “ORAL”) description (str): description string for this drug risk score (float): percentage of risky fields filled in risk_score

USAGE EXAMPLE:

>>> advil = Drug(meta, result)
>>> overview = advil.drug_overview() # returns dict with overview fields

get_date()

OVERVIEW:

Returns date of most recently published drug in the drug query used to collect original json of this drug.

Parameters:

None

RETURN VALUE:

Date (str): date of most recent pull from meta field of drug

USAGE EXAMPLE:

>>> advil = Drug(meta, result)
>>> date = advil.get_date() # returns most recent update date of advil

risk_score()

OVERVIEW:

Returns computed risk dict/score for 9 core categories of risk. If these fields contain any non-None data, they receive a True in the risk dictionary and add to the total risk tally. Total risk tally is taken as a percentage of nine and also returned with function output. Thus, function provides flexibility of seeing which individual risks are True (or exist) and total percentage of risks that this drug carries.

Parameters:

None

RETURN VALUE:

risk_list (list): list containing risk dictionary with booleans and risk score

USAGE EXAMPLE:

>>> advil = Drug(meta, result)
>>> date = advil.risk_score() # returns [advil_risk_info, advil_risk_score]

drug_comprehensive()

OVERVIEW:

Provides a comprehensive dictionary covering all fields contained in results ection of the Drug object. Iterates through json format and appends to all_info dict, returning result.

Parameters:

None

RETURN VALUE:

all_info (dict): dictionary containing all parameters and stored values in Drug

USAGE EXAMPLE:

>>> advil = Drug(meta, result)
>>> date = advil.drug_comprehensive() # returns all parameters and fields in a dict

class open_fda_drug_label.Shelf(capacity: int = 10000)

OVERVIEW:

Shelf is the primary manipulation object to utilize and employ drug objects. Enables optional capacity that dictates the amount of drugs capable of being fit on the shelf. Prevents redundancy of drugs by identifying identical names and preventing addition of same drugs. Enables adding and removing drugs from shelf structure. Enables collection of shelf statistics about total fields, risk score, and other total drug statistics.

This is designed to be useful for individuals storing medicine in their homes, pharmacists keeping track of SKUs and inventory from FDA approved drugs, and to provide a malleable data manipulation object for implementation.

corelist

a list containing all the individual drug items on the shelf.

Type:

list

capacity

total capacity of the shelf (number of drugs) not to be exceeded

Type:

int

USAGE EXAMPLE:

>>> my_shelf = Shelf(capacity=20)
>>> my_shelf.add_drug(Advil) # 1 drug shelf
>>> my_shelf.add_drug(Oxycodone) # 2 drug shelf
>>> my_shelf.remove_drug(Oxycodone.get_name()) # removes based on exact name match
>>> # my_shelf has 1 drug
>>> my_shelf.shelf_stats() # returns the basic descriptive stats for the shelf

corelist = []

capacity = 10000

get_drugs()

OVERVIEW:

Function returns list of all drugs on the shelf

Parameters:

None

RETURN VALUE:

corelist (list): list of all drugs on the shelf

USAGE EXAMPLE:

>>> my_shelf.get_drugs() # returns list of drugs

add_drug(drug)

OVERVIEW:

Function to add a drug to the shelf. Function has a couple of checks; it first ensures that the drug is not already on the list by get_name function, and also ensures that the list is not capacity backed up. After doing so, the function adds the drug to the list.

Parameters:

drug (Drug) – drug to be considered for addition to the list

RETURN VALUE:

None: simply adds drug to the list

USAGE EXAMPLE:

>>> my_shelf = Shelf(capacity=20) # initializes shelf object
>>> my_shelf.add_drug(Advil) # adds advil to the shelf if space/not redundant

remove_drug(name: str)

OVERVIEW:

Function to remove drug from shelf. Takes in string with name of drug and checks entire shelf to see if matching name can be withdrawn. If matching name appears, drug is removed from the list.

Parameters:

name (str) – result of Drug.get_name() for drug desired to be removed

RETURN VALUE:

None

USAGE EXAMPLE:

>>> my_shelf #imagine this is a shelf that has multiple drugs including advil
>>> my_shelf.remove_drug("Advil") # checks get_name for all drugs and removes "Advil"

shelf_stats()

OVERVIEW:

Provides statistics on the shelf, including newest drug, average risk score, average total fields in drug_comprehensive, and percentage_full of the capacity of the shelf in terms of drug count.

Parameters:

None

RETURN VALUE:

shelf_stats (dict): dictionary with 4 key shelf statistics

USAGE EXAMPLE:

>>> my_shelf.shelf_stats() # returns shelf stats if computable for my shelf