Reports

REDCap API methods for Project reports

`Reports (Base)`

Responsible for all API methods under 'Reports' in the API Playground

Source code in redcap/methods/reports.py

class Reports(Base):
    """Responsible for all API methods under 'Reports' in the API Playground"""

    def export_report(
        self,
        report_id: str,
        format_type: Literal["json", "csv", "xml", "df"] = "json",
        raw_or_label: Literal["raw", "label"] = "raw",
        raw_or_label_headers: Literal["raw", "label"] = "raw",
        export_checkbox_labels: bool = False,
        csv_delimiter: Literal[",", "tab", ";", "|", "^"] = ",",
        df_kwargs: Optional[Dict[str, Any]] = None,
    ):
        """
        Export a report of the Project

        Args:
            report_id:
                The report ID number provided next to the report name
                on the report list page
            format_type:
                Format of returned data. `'json'` returns json-decoded
                objects while `'csv'` and `'xml'` return strings.
                `'df'` will attempt to return a `pandas.DataFrame`.
            raw_or_label:
                Export the raw coded values or
                labels for the options of multiple choice fields
            raw_or_label_headers:
                For the CSV headers, export the variable/field names
                (raw) or the field labels (label)
            export_checkbox_labels:
                Specifies the format of
                checkbox field values specifically when exporting the data as labels
                (i.e. when `rawOrLabel=label`). When exporting labels, by default
                (without providing the exportCheckboxLabel flag or if
                exportCheckboxLabel=false), all checkboxes will either have a value
                'Checked' if they are checked or 'Unchecked' if not checked.
                But if exportCheckboxLabel is set to true, it will instead export
                the checkbox value as the checkbox option's label (e.g., 'Choice 1')
                if checked or it will be blank/empty (no value) if not checked
            csv_delimiter:
                For the csv format, choose how the csv delimiter.

        Raises:
            ValueError: Unsupported format specified

        Returns:
            Union[List[Dict[str, Any]], str, pd.DataFrame]: Data from the report ordered by
            the record (primary key of project) and then by event id

        Examples:
            >>> proj.export_report(report_id="4292") # doctest: +SKIP
            [{'record_id': '1', 'redcap_event_name': 'event_1_arm_1',
            'checkbox_field___1': '0', 'checkbox_field___2': '1'}]
        """
        payload = self._initialize_payload(content="report", format_type=format_type)
        keys_to_add = (
            report_id,
            raw_or_label,
            raw_or_label_headers,
            export_checkbox_labels,
            csv_delimiter,
        )
        str_keys = (
            "report_id",
            "rawOrLabel",
            "rawOrLabelHeaders",
            "exportCheckboxLabel",
            "csvDelimiter",
        )
        for key, data in zip(str_keys, keys_to_add):
            data = cast(str, data)
            if data:
                payload[key] = data

        return_type = self._lookup_return_type(format_type, request_type="export")
        response = cast(Union[Json, str], self._call_api(payload, return_type))

        return self._return_data(
            response=response,
            content="report",
            format_type=format_type,
            df_kwargs=df_kwargs,
        )

`def_field: str` `inherited` `property` `readonly`

The 'record_id' field equivalent for a project

`field_names: List[str]` `inherited` `property` `readonly`

Project field names

!!! note These are survey field names, not export field names

`forms: List[str]` `inherited` `property` `readonly`

Project form names

`is_longitudinal: bool` `inherited` `property` `readonly`

Whether or not this project is longitudinal

`metadata: Json` `inherited` `property` `readonly`

Project metadata in JSON format

`token: str` `inherited` `property` `readonly`

API token to a project

`url: str` `inherited` `property` `readonly`

API URL to a REDCap server

`export_report(self, report_id, format_type='json', raw_or_label='raw', raw_or_label_headers='raw', export_checkbox_labels=False, csv_delimiter=',', df_kwargs=None)`

Export a report of the Project

Parameters:

Name	Type	Description	Default
`report_id`	`str`	The report ID number provided next to the report name on the report list page	required
`format_type`	`Literal['json', 'csv', 'xml', 'df']`	Format of returned data. `'json'` returns json-decoded objects while `'csv'` and `'xml'` return strings. `'df'` will attempt to return a `pandas.DataFrame`.	`'json'`
`raw_or_label`	`Literal['raw', 'label']`	Export the raw coded values or labels for the options of multiple choice fields	`'raw'`
`raw_or_label_headers`	`Literal['raw', 'label']`	For the CSV headers, export the variable/field names (raw) or the field labels (label)	`'raw'`
`export_checkbox_labels`	`bool`	Specifies the format of checkbox field values specifically when exporting the data as labels (i.e. when `rawOrLabel=label`). When exporting labels, by default (without providing the exportCheckboxLabel flag or if exportCheckboxLabel=false), all checkboxes will either have a value 'Checked' if they are checked or 'Unchecked' if not checked. But if exportCheckboxLabel is set to true, it will instead export the checkbox value as the checkbox option's label (e.g., 'Choice 1') if checked or it will be blank/empty (no value) if not checked	`False`
`csv_delimiter`	`Literal[',', 'tab', ';', '\|', '^']`	For the csv format, choose how the csv delimiter.	`','`

Exceptions:

Type	Description
`ValueError`	Unsupported format specified

Returns:

Type	Description
`Union[List[Dict[str, Any]], str, pd.DataFrame]`	Data from the report ordered by the record (primary key of project) and then by event id

Examples:

>>> proj.export_report(report_id="4292")
[{'record_id': '1', 'redcap_event_name': 'event_1_arm_1',
'checkbox_field___1': '0', 'checkbox_field___2': '1'}]

Source code in redcap/methods/reports.py

def export_report(
    self,
    report_id: str,
    format_type: Literal["json", "csv", "xml", "df"] = "json",
    raw_or_label: Literal["raw", "label"] = "raw",
    raw_or_label_headers: Literal["raw", "label"] = "raw",
    export_checkbox_labels: bool = False,
    csv_delimiter: Literal[",", "tab", ";", "|", "^"] = ",",
    df_kwargs: Optional[Dict[str, Any]] = None,
):
    """
    Export a report of the Project

    Args:
        report_id:
            The report ID number provided next to the report name
            on the report list page
        format_type:
            Format of returned data. `'json'` returns json-decoded
            objects while `'csv'` and `'xml'` return strings.
            `'df'` will attempt to return a `pandas.DataFrame`.
        raw_or_label:
            Export the raw coded values or
            labels for the options of multiple choice fields
        raw_or_label_headers:
            For the CSV headers, export the variable/field names
            (raw) or the field labels (label)
        export_checkbox_labels:
            Specifies the format of
            checkbox field values specifically when exporting the data as labels
            (i.e. when `rawOrLabel=label`). When exporting labels, by default
            (without providing the exportCheckboxLabel flag or if
            exportCheckboxLabel=false), all checkboxes will either have a value
            'Checked' if they are checked or 'Unchecked' if not checked.
            But if exportCheckboxLabel is set to true, it will instead export
            the checkbox value as the checkbox option's label (e.g., 'Choice 1')
            if checked or it will be blank/empty (no value) if not checked
        csv_delimiter:
            For the csv format, choose how the csv delimiter.

    Raises:
        ValueError: Unsupported format specified

    Returns:
        Union[List[Dict[str, Any]], str, pd.DataFrame]: Data from the report ordered by
        the record (primary key of project) and then by event id

    Examples:
        >>> proj.export_report(report_id="4292") # doctest: +SKIP
        [{'record_id': '1', 'redcap_event_name': 'event_1_arm_1',
        'checkbox_field___1': '0', 'checkbox_field___2': '1'}]
    """
    payload = self._initialize_payload(content="report", format_type=format_type)
    keys_to_add = (
        report_id,
        raw_or_label,
        raw_or_label_headers,
        export_checkbox_labels,
        csv_delimiter,
    )
    str_keys = (
        "report_id",
        "rawOrLabel",
        "rawOrLabelHeaders",
        "exportCheckboxLabel",
        "csvDelimiter",
    )
    for key, data in zip(str_keys, keys_to_add):
        data = cast(str, data)
        if data:
            payload[key] = data

    return_type = self._lookup_return_type(format_type, request_type="export")
    response = cast(Union[Json, str], self._call_api(payload, return_type))

    return self._return_data(
        response=response,
        content="report",
        format_type=format_type,
        df_kwargs=df_kwargs,
    )

Reports

Reports (Base)

def_field: str inherited property readonly

field_names: List[str] inherited property readonly

forms: List[str] inherited property readonly

is_longitudinal: bool inherited property readonly

metadata: Json inherited property readonly

token: str inherited property readonly

url: str inherited property readonly

export_report(self, report_id, format_type='json', raw_or_label='raw', raw_or_label_headers='raw', export_checkbox_labels=False, csv_delimiter=',', df_kwargs=None)