CastorClient

CastorClient supplies the key functionality of the package. It authenticates the user to the Castor API and has defined functions to interact with all the endpoints defined in the API. It allows for direct querying of database endpoints, but requires some knowledge of programming in Python. Examples of endpoints are creating a new survey package for a study participant, updating study data for a participant or retrieving information about the study. For an example, see Code Snippet 1.

from castoredc_api import CastorClient
# Create a client with your credentials
c = CastorClient('MYCLIENTID', 'MYCLIENTSECRET', 'data.castoredc.com')
# Link the client to your study in the Castor EDC database
c.link_study('MYSTUDYID')
# Then you can interact with the API
# Get all records in the study
c.all_records()
# Create a new survey package
c.create_survey_package_instance(survey_package_id="SURVEY-PACKAGE-ID",
                        record_id="TEST-001",
                        email_address="example@fakemail.com",
                        auto_send=True)

CastorStudy

CastorStudy is a local representation of the researcher’s study database. It downloads the raw study data through the API using the CastorClient module in the background and then augments and formats the study for easy searching. The local representation is split into two parts: one part defines the structure of the study and the other part defines the data collected in the study. For a visualisation of the study structure, see Figures 1 and 2.

The structure of a study is defined at the upper level by forms. These can consist of different types: study, report or survey. A study form is a planned phase in the study, a report form is an unscheduled or repeated event, and a survey form is a survey or electronic patient-reported outcome measure. Each form consist of a collection of fields which are the variables specified by the study protocol to be collected. Forms and fields can be considered the templates in which data per record is filled.

The data of the study is defined at the upper level by records. Each record is a study patient and is linked to a collection of form instances. These are instances of the study, report and survey forms and contain information on among other things when forms were created and filled in. Each form instance contains a collection of data points, which are instances of fields. These hold values and information for each variable in the study per record.

Mapping the study structure locally allows the researcher to quickly find specific fields or forms and is used when validating data to be imported. After the study structure is mapped, a representation of the study is created in Python. This only contains forms, steps and fields, and can be seen as the case report forms of the study and does not include data. When importing data, the structure is used to assess if fields exist in the study and validate values. Moreover, one can search for specific fields or forms in the structure to get information on these fields, see Code Snippet 2.

from castoredc_api import CastorStudy
# Link to Castor database
study = CastorStudy('MYCLIENTID', 'MYCLIENTSECRET', 'MYSTUDYID', 'data.castoredc.com')

# Map only the study structure locally
study.map_structure()
# Find the field labelled “med_name”
field = study.get_single_field(“med_name”)

# Map the study data locally (also maps structure)
study.map_data()
# Get all data points in the study
data_points = study.get_all_data_points()

# Export your study to pandas dataframes or CSV files
study.export_to_dataframe()
study.export_to_csv()

One can also map the study data, which first maps the study structure and then exports all data from the Castor database, linking it to the structure and allowing the data to be accessed as Python objects. These functions are used to export data from the API to data analysis tools such as Python (pandas) and R [11]. For examples, see Code Snippet 2.

Importer

The importer can be used to read, clean, validate and import RWD into the Castor database. The importer is started by calling the function import_data with a set of configuration options. First the simple case of uploading data is shown, thereafter the complex options are described. In all cases the main input is the data to be imported, a xls(x) file with records as rows and variables as columns (Table 1).

This is combined with a second xls(x) file that maps the columns in the data file to the fields in the Castor database (Table 2). Headers “other” and “castor” are obligatory. For special cases, for example checkbox, radio or dropdown fields that define an ‘other’ option, see the software documentation [11].

There are three other options that need to be specified when uploading data. These are the study, whether the data is labelled and what the target is of the import. The study is defined by a CastorStudy (see above). Labelled data defines whether data in the data file contains labels (woman/man) or values (0/1) for data points that use an option group. The target defines whether the data to be imported are for a study, report or survey form. When importing report or survey data, it is also necessary to define the name of the report or survey. When uploading survey data a fall-back (fake or researcher owned) e-mail address needs to be supplied. While the surveys are not sent to this e-mail address, the database does not accept survey instances without a fall-back e-mail address. For examples of each data type, see Code Snippet 3.

from castoredc_api import CastorStudy
from castoredc_api import import_data
# Link to Castor database
study = CastorStudy('MYCLIENTID', 'MYCLIENTSECRET', 'MYSTUDYID', 'data.castoredc.com')
# Import labelled study data
imported_data = import_data(data_source_path="studydatafile.xlsx",
                        column_link_path="studylinkfile.xlsx",
                        study=study,
                        label_data=True,
                        target="Study")
# Import non-labelled report data
imported_data = import_data(data_source_path="reportdatafile.xlsx",
                        column_link_path="reportlinkfile.xlsx",
                        study=study,
                        label_data=False,
                        target="Report",
                        target_name="Medication")
# Import labelled survey data
imported_data = import_data(data_source_path="surveydatafile.xlsx",
                        column_link_path="surveylinkfile.xlsx",
                        study=study,
                        label_data=True,
                        target="Survey",
                        target_name="Example Survey Package",
                        email="example@fakemail.com")

Before uploading the data file to the Castor database, the package prepares the data for import and validates all values. Every column in the data file is checked to see whether a target field exists and is part of the target. Every record is checked to determine whether it exists in the study. All labelled data is translated to the corresponding values if applicable. For all columns the values to be imported are checked against minimum or maximum allowed values (numeric and year fields), the allowed option groups (dropdown, radio and checkbox fields), and the correct formatting (date, datetime and time fields). When one or more errors are encountered in the data file, the process is aborted and the program outputs a file indicating for which values an error was found.

The import_data function can be supplied with some extra configuration options for complex situations. These are translating variable names between databases, merging multiple variables into one, formatting options and an option for asynchronous interaction with the API. See the software documentation [11].

Archive

Name: CastorEDC API

Persistent identifier: https://pypi.org/project/castoredc-api/

Licence: MIT

Publisher: Reinier Cornelis Anthonius van Linschoten

Version published: v0.1.9.1

Date published: 13/07/2023