Lightweight, user-friendly Python client for the REDCap API.

redcaplite makes it easy to connect to your REDCap project and perform common operations with minimal code. Whether you're a researcher automating data pulls or a developer building integrations, redcaplite keeps things simple and efficient.

• Intuitive interface for the most common REDCap API endpoints.
• Installable from PyPI and ready to use in seconds.
• Fully typed and tested for reliable data exchange.
• Minimal dependencies to keep your environment lean.

Before using redcaplite, you need to obtain two key pieces of information from your REDCap project's API page:

• API URL: The web address (URL) for your REDCap API.
• API Token: Your unique access token for authenticating API requests to your REDCap project.

To install redcaplite from the Python Package Index (PyPI), run the following command in your terminal:

pip install redcaplite

This is the recommended installation method for most users.

If you plan to contribute to redcaplite or require the latest development version, you can install it directly from the source code:

1. Clone the repository:

   git clone https://github.com/jubilee2/RedcapLite.git

2. Navigate to the cloned directory:

   cd RedcapLite

3. Install the package in editable mode (this allows your changes to be immediately reflected):

   pip install -e .

This setup installs the package locally, making any modifications to the source code instantly available in your environment.

Here's a quick example to get you started with redcaplite. This snippet demonstrates how to initialize the client and fetch basic project information.

from redcaplite import RedcapClient

# Replace 'YOUR_REDCAP_API_URL' and 'YOUR_REDCAP_API_TOKEN' with your actual API URL and token.
API_URL = 'YOUR_REDCAP_API_URL'
API_TOKEN = 'YOUR_REDCAP_API_TOKEN'

# Create a RedcapClient instance
try:
    client = RedcapClient(API_URL, API_TOKEN)

    # Get basic project information
    project_info = client.get_project()
    print("Project Information:")
    if project_info: # project_info will be a dictionary on success
        print(f"  Project ID: {project_info.get('project_id')}")
        print(f"  Project Title: {project_info.get('project_title')}")
        print(f"  REDCap Version: {project_info.get('redcap_version')}")
    else:
        # This else block might be reached if the API returns an unexpected empty response
        # or if client.get_project() itself returns None on certain errors (check its implementation).
        print("Could not retrieve project information. The response was empty or unexpected.")
        print("Please verify your API URL, token, and project permissions.")

except Exception as e:
    print(f"An error occurred during API interaction: {e}")
    print("Please ensure your API URL and token are correct, the REDCap API is accessible, and your project has API permissions enabled.")

To use redcaplite in your Python script, import the necessary components:

import redcaplite # Or, more commonly:
# from redcaplite import RedcapClient

Instantiate the RedcapClient class by providing your REDCap API URL and token:

from redcaplite import RedcapClient

# Replace with your actual API URL and token
API_URL = 'YOUR_REDCAP_API_URL' # e.g., 'https://redcap.yourinstitution.org/api/'
API_TOKEN = 'YOUR_REDCAP_API_TOKEN' # e.g., 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'

client = RedcapClient(API_URL, API_TOKEN)
# Now 'client' can be used to call various API methods.
# For example: project_details = client.get_project()
# It's good practice to wrap API calls in try-except blocks, as shown in the Quick Start section.

The RedcapClient provides a wide range of methods to interact with the REDCap API. Here is a comprehensive list, categorized by typical REDCap actions (Export, Import, Delete). Not all actions are available for every API endpoint.

Here’s a complete example of how to use the redcaplite package:

import redcaplite

# Create an instance of RedcapClient
r = redcaplite.RedcapClient('https://redcap.vumc.org/api/', 'your_token')

# Get arms
arms = r.get_arms()
print("Arms:", arms)

# Delete specific arms
r.delete_arms(arms=[3])
print("Arm 3 deleted successfully.")

When exporting data in CSV format using methods like export_records() or get_report(), redcaplite internally uses pandas.read_csv() to parse the initial response from REDCap. The pd_read_csv_kwargs parameter allows you to pass additional keyword arguments directly to pandas.read_csv(), giving you finer control over data type conversion and other parsing aspects.

A common use case for pd_read_csv_kwargs is to specify the data type of specific columns. For instance, to ensure a column like participant_study_id is treated as a string (preventing automatic conversion to a numeric type if it contains only digits), you can do the following:

# When calling export_records or get_report
response = client.export_records(
    format='csv', 
    # ... other parameters ...
    pd_read_csv_kwargs={'dtype': {'participant_study_id': str}}
)
# Or for a specific report:
# report_data = client.get_report(
#     report_id='YOUR_REPORT_ID',
#     format='csv',
#     pd_read_csv_kwargs={'dtype': {'participant_study_id': str, 'another_id_field': str}}
# )

In this example, the dtype dictionary passed within pd_read_csv_kwargs instructs pandas to treat the participant_study_id column as str (string).

• Preserve Data Integrity: Ensure that sensitive data, like participant IDs, are maintained in their original string format, preventing unintended numeric conversions.
• Avoid Downstream Errors: Prevent issues related to automatic data type conversions that might cause errors or unexpected behavior in subsequent data processing steps.
• Leverage Pandas Power: Utilize pandas' robust data type handling capabilities to fine-tune your data parsing directly at the point of API interaction.

This feature is particularly useful for maintaining data consistency, especially for columns that might contain leading zeros or mixed alphanumeric characters but could be misinterpreted as numeric.

We hope this new feature helps you to work more efficiently and effectively with your REDCap data!

Contributions to redcaplite are welcome! If you would like to contribute, please fork the repository, make your changes, and submit a pull request.

This project is licensed under the MIT License - see the LICENSE file for details.