PyCap: Python interface to REDCap
Project description
This project is community maintained. Please continue to submit bugs and feature requests, though it’s the community’s responsibility to address them.
Intro
PyCap is a python module exposing the REDCap API through some helpful abstractions. Information about the REDCap project can be found at http://project-redcap.org/.
Available under the MIT license.
Documentation
Canonical documentation can be found on ReadTheDocs.
Features
Currently, these API calls are available:
Export Records
Export Metadata
Import Metadata
Delete Records
Import Records
Export File
Import File
Delete File
Export Users
Export Form Event Mappings
Export Reports
Events and Arms are automatically exported for longitudinal projects (see below).
Requirements
requests (>= 1.0.0)
$ pip install requests
Usage
>>> import redcap
# Init the project with the api url and your specific api key
>>> project = redcap.Project(api_url, api_key)
# Export all data
>>> all_data = project.export_records()
# import data
>>> data = [{'subjid': i, 'age':a} for i, a in zip(range(1,6), range(7, 13))]
>>> num_processed = project.import_records(data)
# For longitudinal projects, project already contains events, arm numbers
# and arm names
>>> print project.events
...
>>> print project.arm_nums
...
>>> print project.arm_names
...
# Import files
>>> fname = 'your_file_to_upload.txt'
>>> with open(fname, 'r') as fobj:
... project.import_file('1', 'file_field', fname, fobj)
# Export files
>>> file_contents, headers = project.export_file('1', 'file_field')
>>> with open('other_file.txt', 'w') as f:
... f.write(file_contents)
# Delete files
>>> try:
... project.delete_file('1', 'file_field')
... except redcap.RedcapError:
... # This throws if an error occured on the server
... except ValueError:
... # This throws if you made a bad request, e.g. tried to delete a field
... # that isn't a file
# Delete record
>>> response = project.delete_record('1')
# Export form event mappings
>>> fem = project.export_fem()
...
# Export Reports
>>> reports = project.export_reports(['1','2'])
Installation
Install with pip
$ pip install PyCap
Install extra requirements, which allows returning project data as a pandas.DataFrame
$ pip install PyCap[pandas]
Install from GitHub
$ git clone git://github.com/redcap-tools/PyCap.git PyCap $ cd PyCap $ python setup.py install
Contributing
1. Create a virtual environment and activate it
$ python -m venv .venv $ source .venv/Scripts/activate
2. Install pip-tools.
$ pip install pip-tools
3. Install all project dependencies
$ pip-sync requirements.txt dev-requirements.txt
4. Install the package, with a link to the source code. This ensures any changes you make are immendiate available to test.
$ python setup.py develop
5. Add your changes and make sure your changes pass all tests
$ pytest
Finally, start a pull request!
Citing
If you use PyCap in your research, please consider citing the software:
Burns, S. S., Browne, A., Davis, G. N., Rimrodt, S. L., & Cutting, L. E. PyCap (Version 1.0) [Computer Software]. Nashville, TN: Vanderbilt University and Philadelphia, PA: Childrens Hospital of Philadelphia. Available from https://github.com/redcap-tools/PyCap. doi:10.5281/zenodo.9917
HISTORY
1.1.3 (2020-11-05)
- API Support
Add support for import_metadata endpoint (#145 @JuliaSprenger)
- Documentation
Update contributing.rst with new installation instructions (#135 @njvack)
1.1.2 (2020-11-05)
- API Support
Add support for exportFieldNames call (#125 @chgreer)
Add dateRangeBegin and dateRangeEnd parameters to Project.export_records (#124 @chgreer)
- Package Improvements
Use pytest for full test suite (#132)
Enforce black and pylint style and formatting on project (#132)
Deprecate support for Python 2 (#132)
Add pandas as an extra_requires (#132)
- Documentation
Update README with new community support model and how to contribute (#132)
1.1.1 (2020-08-18)
- Bug Fixes
Fix package version parsing for UNIX (#122 @fissell)
1.1.0 (2020-07-16)
- API Support
Add rec_type support in import_records() (#40 @dckc)
Add export_checkbox_labels keyword arg to export_records() (#48 Tyler Rivera)
Properly backfill requested fields for >6.X servers (#55)
Add Export Survey Participant List method (#71)
Add filter_logic to export_records (#85 @erikh360)
Add forceAutoNumber parameter to import_records() (#86 @CarlosBorroto)
Add Export Project Information (#106 @martinburchell)
Add Generate Next Record Name (#107 @martinburchell)
Add repeat_instance parameter to imp_file request (#104 @martinburchell)
Add Delete Record (#77 @damonms)
Add Export Reports (#91 @mcarmack)
- Package Improvements
Add redcap_version attribute to Project (#44 Tyler Rivera)
Support lazy loading of Projects (#53 Tyler Rivera)
Add Python 3 support (#67, #92 @jmillxyz, @fonnesbeck)
Remove obsolete Project.filter() (#105 @martinburchell)
Change API parameters from comma-separated to arrays (#110 @martinburchell)
Use single requests.Session() for connections (#120 @KarthikMasi)
- Bug Fixes
Allow later versions of semantic-version (#108 @martinburchell)
Fix package version when installing from GitHub (#113)
Handle EmptyData error from pandas read_csv (#118 @martinburchell)
- Documentation
Added REDCap API changelog from 6.0.0 - 6.12.1 (#64 @SlightlyUnorthodox)
Python 3 updates (#115 @sujaypatil96)
1.0.2 (2016-10-05)
Fix issue in new survey participant export method.
1.0.1 (2016-10-05)
Add a Project method to export the survey participant list.
Update author email.
1.0 (2014-05-16)
Normalize all format argument to default to json, not obj. This better follows the official REDCap API. This breaks backwards compatibility, hence the 1.0 release.
Remove the redcap.query and associated tests. If you need filtering functionality, Pandas is highly recommended.
Update documentation re: how PyCap implicitly decodes JSON responses.
0.9 (2014-02-27)
Update docs about passing CA_BUNDLE through verify_ssl.
Canonical URL for docs is now http://pycap.rtfd.org.
Add date_format argument for .import_records
Sphinxification of docs
Add MIT license
Add export_survey_fields & export_data_access_groups arguments for .import_records
Raise for 5XX responses
Raise exception for failed imports
Deprecate the entire redcap.Query module. It was a bad idea to begin with.
Raise exception during Project instantiation when the metadata call fails. This is usually indicative of bad credentials.
0.8.1 (2013-05-16)
By default, in longitudinal projects when exporting records as a data frame, the index will be a MultiIndex of the project’s primary field and redcap_event_name.
DataFrames can be passed to Project.import_records.
Added Project.export_fem to export Form-Event Mappings from the Project.
The SSL certificate on REDCap server can be ignored if need be.
0.8.0 (2013-02-14)
- Added rest of API methods: Project.export_users, Project.delete_file. Almost
all API methods are implemented within Project in some way, shape or form.
Fix file import bug.
Now use relaxed JSON decoding because REDCap doesn’t always send strict JSON.
- File export, import and delete methods will raise redcap.RedcapError when the
methods don’t succeed on the server.
Low-level content handling has been cleaned up.
0.7.0 (2013-01-18)
Added Project.export_file and Project.import_file methods for exporting/ importing files from/to REDCap databases
Fixed a dependency issue that would cause new installations to fail
Fixed an issue where newline characters in the project’s Data Dictionary would case Projects to fail instantiation.
0.6.1 (2012-11-16)
Add ability to alter DataFrame construction with the ‘df_kwargs’ arg in Project.export_records and .export_metadata
0.6 (2012-11-06)
Add export_metadata function on redcap.Project class
- Add ‘df’ as an option for the format argument on the redcap.Project
export methods to return a pandas.DataFrame
0.5.2 (2012-10-12)
Update setup.py for more graceful building
0.5.1 (2012-10-04)
Fix potential issue when exporting strange characters
0.5 (2012-09-19)
Add initial support for longitudinal databases
Add helper attributes on redcap.Project class
Improve testing
Add Travis-CI testing on github
0.4.2 (2012-03-15)
0.4.1 didn’t play well with pypi?
0.4.1 (2012-03-15)
Defend against non-unicode characters in Redcap Project
0.3.4 (2012-01-12)
New documentation
0.3.3 (2011-11-21)
Bug fix when exporting all fields
0.3.2 (2011-11-21)
Works with current version of requests
Under-the-hood changes (only json is used for RCRequest)
Bug fix in Project.filter
0.3.1 (2011-11-02)
Bug fix in import_records
0.3 (2011-09-27)
Using Kenneth Reitz’s request module, greatly simplifying request code.
0.21 (2011-09-14)
First public release on PyPI
Version bump
0.1 (2011-09-14)
Basic import, export, metadata
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
