redcap_api package

Submodules

redcap_api.redcap_api_interface module

Module: contains class REDCapInterface, providing a wrapper around the REDCap API.

class redcap_api.redcap_api_interface.REDCapInterface(isdev: bool = False, timeout_sec: int = 10)

Bases: object

Wrapper class around the REDCap API.

…

no public attributes
Methods(starting in CRUD order)
-------
create(data_records)

Inserts new records from a dict, list of dicts or a dataframe. Assumes user has included the study_id in each new record.

retrieve

When called without argument, retrieves ALL the records in the database.

retrieve(record_numbers)

When called with either a single record number or a list of numbers, retrieves those records.

update(data_record)

Overwrites the existing record at the study_id record number in the argument dict or dataframe. If there is no existing record with that study_id, creates a new record. Only overwrites the properties present in the input argument.

delete(record_number)

Deletes the data record at the specified study_id value.

exists(record_number)

Returns whether the specified record number exists in the database.

last_record_number

Returns the highest study_id value present in the database.

next_record_number

Returns the next unused study_id value; used in creating new record.

version

Returns the version number of the REDCap API in use.

create(data_records: Union[dict, DataFrame]) → bool

Insert new records into database.

Parameters:

data_records (dict, dataframe) – Must contain the new study_id desired.

Return type:

bool

Examples

>>> from src.redcap_api import REDCapInterface
>>>
>>>
>>> redcap_interface_object = REDCapInterface()
>>> new_data = {'study_id': '12345', 'name': "Patient's Name", 'mrn': '000000', ...}
>>> redcap_interface_object.create(new_data)
delete(record_number: int) → bool

Insert new records into database.

Parameters:

record_number (int) – The study_id of the record to delete.

Return type:

bool

Examples

>>> from src.redcap_api import REDCapInterface
>>>
>>>
>>> redcap_interface_object = REDCapInterface()
>>> redcap_interface_object.delete(12345)
exists(record_number: Optional[int] = None) → bool

See if given record number exists in the database.

Parameters:

record_number (int) – The value of the study_id field in the desired record.

Returns:

Was that record_number found?

Return type:

bool

Examples

>>> from src.redcap_api import REDCapInterface
>>>
>>>
>>> redcap_interface_object = REDCapInterface()
>>>
>>> if redcap_interface_object.exists(record_number): ...
last_record_number(except_for: Optional[Union[int, list]] = None, number_desired: int = 1) → Union[int, list]

Lookup the highest record number (study_id) present in the database.

Parameters:

  • except_for (int, list) – Record numbers to skip over.

  • number_desired (int, optional) – How many numbers to return. default is 1

Return type:

int or list of ints

Examples

>>> from src.redcap_api import REDCapInterface
>>>
>>>
>>> redcap_interface_object = REDCapInterface()
>>> highest_record_number_in_use = redcap_interface_object.last_record_number()
next_record_number() → int

Lookup next available record number.

Used when creating a new record.

Return type:

int

Examples

>>> from src.redcap_api import REDCapInterface
>>>
>>>
>>> redcap_interface_object = REDCapInterface()
>>> new_record_number = redcap_interface_object.next_record_number()
retrieve(record_numbers: Optional[Union[int, list]] = None, expanded_record: bool = False) → DataFrame

Get particular record(s) or all the records.

Parameters:

  • record_numbers (int or list, optional) – If specified, returns just that/those record(s). If None or unspecified, returns all the records. default is None

  • expanded_record (bool, optional) – If true, returns all the fields available. Otherwise, returns study_id, dob, primary_consent_date, core_participant_date, date_of_last_activity default is False

Return type:

dataframe

Examples

>>> from src.redcap_api import REDCapInterface
>>>
>>>
>>> redcap_interface_object = REDCapInterface()
>>> df_all = redcap_interface_object.retrieve()
>>> df_selected = redcap_interface_object.retrieve([1234, 2345])
update(new_data_records: Optional[Union[dict, DataFrame]] = None) → bool

Change an existing record.

Since there is no native “update” method in the REDCap API, this wrapper method: 1. makes two copies of the existing record: one to modify, one as a backup 2. deletes the existing record 3. modifies the copy of the existing record 4. tries to insert the modified record into the database under the same study_id 5. if the insert fails, tries to restore the backup copy of the record by inserting that into the database under the same study_id 6. if unable to insert the backup, throws an exception

Parameters:

new_data_records (dict or dataframe) –

Return type:

bool

Examples

>>> from src.redcap_api import REDCapInterface
>>>
>>>
>>> redcap_interface_object = REDCapInterface()
>>> new_info = {'study_id': str(record_number_to_update),
>>>             'date_of_last_activity': right_now}
>>> redcap_interface_object.update(new_info)
version() → str

Ask REDCap API for its software version number.

Return type:

str

Examples

>>> from src.redcap_api import REDCapInterface
>>>
>>>
>>> redcap_interface_object = REDCapInterface()
>>> print(f"Version = {redcap_interface_object.version()}")

Module contents

REDCap API Calls

A wrapper around the REDCap API, allowing Python code to connect with the API.