Skip to main content
This is a pre-production deployment of Warehouse. Changes made here affect the production instance of PyPI (pypi.python.org).
Help us improve Python packaging - Donate today!

PyCap: Python interface to REDCap

Project Description
**I am no longer actively developing this code base. Please continue to submit bugs and I'll do my best to tackle them.**

.. image:: https://secure.travis-ci.org/sburns/PyCap.png?branch=master
.. image:: https://zenodo.org/badge/3886/sburns/PyCap.png

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 <http://pycap.rtfd.org>`_.

Features
--------

Currently, these API calls are available:

- Export Records
- Export Metadata
- Import Records
- Export File
- Import File
- Delete File
- Export Users
- Export Form Event Mappings

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

# Export form event mappings
>>> fem = project.export_fem()
...

Installation
------------
::

$ git clone git://github.com/sburns/PyCap.git PyCap
$ cd PyCap
$ python setup.py install

OR

$ pip install PyCap

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/sburns/PyCap. doi:10.5281/zenodo.9917


HISTORY
-------

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 <http://pandas.pydata.org>`_ 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 <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 History

This version
History Node

1.0.2

History Node

1.0.1

History Node

1.0

History Node

0.9

History Node

0.8.1

History Node

0.8

History Node

0.7

History Node

0.6.1

History Node

0.6

History Node

0.5.2

History Node

0.5.1

History Node

0.5

History Node

0.4.2

History Node

0.4

History Node

0.3.4

History Node

0.3.2

History Node

0.3

History Node

0.2

History Node

0.1

Download Files

Download Files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

File Name & Checksum SHA256 Checksum Help Version File Type Upload Date
PyCap-1.0.2-py27-none-any.whl (17.5 kB) Copy SHA256 Checksum SHA256 2.7 Wheel Oct 5, 2016
PyCap-1.0.2.tar.gz (16.9 kB) Copy SHA256 Checksum SHA256 Source Oct 5, 2016

Supported By

WebFaction WebFaction Technical Writing Elastic Elastic Search Pingdom Pingdom Monitoring Dyn Dyn DNS Sentry Sentry Error Logging CloudAMQP CloudAMQP RabbitMQ Heroku Heroku PaaS Kabu Creative Kabu Creative UX & Design Fastly Fastly CDN DigiCert DigiCert EV Certificate Rackspace Rackspace Cloud Servers DreamHost DreamHost Log Hosting