Surveys

REDCap API methods for Project surveys

`Surveys (Base)`

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

Source code in redcap/methods/surveys.py

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

    def export_survey_link(
        self,
        record: str,
        instrument: str,
        event: Optional[str] = None,
        repeat_instance: int = 1,
    ) -> str:
        """
        Export one survey link

        Note:
            The passed instrument must be set up as a survey instrument.

        Args:
            record:
                Name of the record
            instrument:
                Name of instrument as seen in the Data Dictionary (metadata).
            event:
                Unique event name, only used in longitudinal projects
            repeat_instance:
                only for projects with repeating instruments/events)
                The repeat instance number of the repeating event (if longitudinal)
                or the repeating instrument (if classic or longitudinal).
                Default value is '1'.

        Returns:
            URL of survey link requested

        Examples:
            >>> proj.export_survey_link(record="1", instrument="form_1", event="event_1_arm_1")
            'https://redcapdemo.vumc.org/surveys/?s=...'
        """
        payload = self._initialize_payload(
            content="surveyLink",
            # Hard-coded due to the nature of the response
            return_format_type="csv",
        )

        payload["record"] = record
        payload["instrument"] = instrument
        payload["repeat_instance"] = repeat_instance

        if event:
            payload["event"] = event

        return cast(str, self._call_api(payload, return_type="str"))

    def export_survey_queue_link(
        self,
        record: str,
    ) -> str:
        """
        Export one survey queue link

        Note:
            The passed instrument must be set up as a survey instrument. The
            survey queue must be enabled for the project.

        Args:
            record:
                Name of the record

        Returns:
            URL of survey queue link requested

        Examples:
            >>> proj.export_survey_queue_link(record="1")
            'https://redcapdemo.vumc.org/surveys/?sq=...'
        """
        payload = self._initialize_payload(
            content="surveyQueueLink",
            # Hard-coded due to the nature of the response
            return_format_type="csv",
        )

        payload["record"] = record

        return cast(str, self._call_api(payload, return_type="str"))

    def export_survey_access_code(
        self,
        record: str,
        instrument: str,
        event: Optional[str] = None,
        repeat_instance: int = 1,
    ) -> str:
        # pylint: disable=line-too-long
        """
        Export a Survey Access Code for a Participant

        Note:
            The passed instrument must be set up as a survey instrument.

        Args:
            record:
                Name of the record
            instrument:
                Name of instrument as seen in the Data Dictionary (metadata).
            event:
                Unique event name, only used in longitudinal projects
            repeat_instance:
                only for projects with repeating instruments/events)
                The repeat instance number of the repeating event (if longitudinal)
                or the repeating instrument (if classic or longitudinal).
                Default value is '1'.

        Returns:
            A survey access code for a specified record and data collection
            instrument

        Examples:
            >>> proj.export_survey_access_code(record="1", instrument="form_1", event="event_1_arm_1")
            '...'
        """
        # pylint: enable=line-too-long
        payload = self._initialize_payload(
            content="surveyAccessCode",
            # Hard-coded due to the nature of the response
            return_format_type="csv",
        )

        payload["record"] = record
        payload["instrument"] = instrument
        payload["repeat_instance"] = repeat_instance

        if event:
            payload["event"] = event

        return cast(str, self._call_api(payload, return_type="str"))

    def export_survey_return_code(
        self,
        record: str,
        instrument: str,
        event: Optional[str] = None,
        repeat_instance: int = 1,
    ) -> str:
        # pylint: disable=line-too-long
        """
        Export a Survey Return Code for a Participant

        Note:
            The passed instrument must be set up as a survey instrument, which has return codes enabled.

        Args:
            record:
                Name of the record
            instrument:
                Name of instrument as seen in the Data Dictionary (metadata).
            event:
                Unique event name, only used in longitudinal projects
            repeat_instance:
                only for projects with repeating instruments/events)
                The repeat instance number of the repeating event (if longitudinal)
                or the repeating instrument (if classic or longitudinal).
                Default value is '1'.

        Returns:
            A survey return code for a specified record and data collection
            instrument

        Examples:
            >>> proj.export_survey_return_code(record="1", instrument="form_1", event="event_1_arm_1")
            '...'
        """
        # pylint: enable=line-too-long
        payload = self._initialize_payload(
            content="surveyReturnCode",
            # Hard-coded due to the nature of the response
            return_format_type="csv",
        )

        payload["record"] = record
        payload["instrument"] = instrument
        payload["repeat_instance"] = repeat_instance

        if event:
            payload["event"] = event

        return cast(str, self._call_api(payload, return_type="str"))

    def export_survey_participant_list(
        self,
        instrument: str,
        format_type: Literal["json", "csv", "xml", "df"] = "json",
        event: Optional[str] = None,
        df_kwargs: Optional[Dict[str, Any]] = None,
    ):
        """
        Export the Survey Participant List

        Note:
            The passed instrument must be set up as a survey instrument.

        Args:
            instrument:
                Name of instrument as seen in the Data Dictionary (metadata).
            format_type:
                Format of returned data
            event:
                Unique event name, only used in longitudinal projects
            df_kwargs:
                Passed to `pandas.read_csv` to control construction of
                returned DataFrame. By default, nothing

        Returns:
            Union[List[Dict[str, Any]], str, pandas.DataFrame]:
                List of survey participants,
                along with other useful
                metadata such as the record, response status, etc.

        Examples:
            >>> proj.export_survey_participant_list(instrument="form_1", event="event_1_arm_1")
            [{'email': '',
            ...
            'survey_access_code': ...},
            {'email': '',
            ...
            'survey_access_code': ...}]
        """
        payload = self._initialize_payload(
            content="participantList",
            format_type=format_type,
        )
        payload["instrument"] = instrument
        if event:
            payload["event"] = event

        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="participantList",
            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_survey_access_code(self, record, instrument, event=None, repeat_instance=1)`

Export a Survey Access Code for a Participant

!!! note The passed instrument must be set up as a survey instrument.

Parameters:

Name	Type	Description	Default
`record`	`str`	Name of the record	required
`instrument`	`str`	Name of instrument as seen in the Data Dictionary (metadata).	required
`event`	`Optional[str]`	Unique event name, only used in longitudinal projects	`None`
`repeat_instance`	`int`	only for projects with repeating instruments/events) The repeat instance number of the repeating event (if longitudinal) or the repeating instrument (if classic or longitudinal). Default value is '1'.	`1`

Returns:

Type	Description
`str`	A survey access code for a specified record and data collection instrument

Examples:

>>> proj.export_survey_access_code(record="1", instrument="form_1", event="event_1_arm_1")
'...'

Source code in redcap/methods/surveys.py

def export_survey_access_code(
    self,
    record: str,
    instrument: str,
    event: Optional[str] = None,
    repeat_instance: int = 1,
) -> str:
    # pylint: disable=line-too-long
    """
    Export a Survey Access Code for a Participant

    Note:
        The passed instrument must be set up as a survey instrument.

    Args:
        record:
            Name of the record
        instrument:
            Name of instrument as seen in the Data Dictionary (metadata).
        event:
            Unique event name, only used in longitudinal projects
        repeat_instance:
            only for projects with repeating instruments/events)
            The repeat instance number of the repeating event (if longitudinal)
            or the repeating instrument (if classic or longitudinal).
            Default value is '1'.

    Returns:
        A survey access code for a specified record and data collection
        instrument

    Examples:
        >>> proj.export_survey_access_code(record="1", instrument="form_1", event="event_1_arm_1")
        '...'
    """
    # pylint: enable=line-too-long
    payload = self._initialize_payload(
        content="surveyAccessCode",
        # Hard-coded due to the nature of the response
        return_format_type="csv",
    )

    payload["record"] = record
    payload["instrument"] = instrument
    payload["repeat_instance"] = repeat_instance

    if event:
        payload["event"] = event

    return cast(str, self._call_api(payload, return_type="str"))

`export_survey_link(self, record, instrument, event=None, repeat_instance=1)`

Export one survey link

!!! note The passed instrument must be set up as a survey instrument.

Parameters:

Name	Type	Description	Default
`record`	`str`	Name of the record	required
`instrument`	`str`	Name of instrument as seen in the Data Dictionary (metadata).	required
`event`	`Optional[str]`	Unique event name, only used in longitudinal projects	`None`
`repeat_instance`	`int`	only for projects with repeating instruments/events) The repeat instance number of the repeating event (if longitudinal) or the repeating instrument (if classic or longitudinal). Default value is '1'.	`1`

Returns:

Type	Description
`str`	URL of survey link requested

Examples:

>>> proj.export_survey_link(record="1", instrument="form_1", event="event_1_arm_1")
'https://redcapdemo.vumc.org/surveys/?s=...'

Source code in redcap/methods/surveys.py

def export_survey_link(
    self,
    record: str,
    instrument: str,
    event: Optional[str] = None,
    repeat_instance: int = 1,
) -> str:
    """
    Export one survey link

    Note:
        The passed instrument must be set up as a survey instrument.

    Args:
        record:
            Name of the record
        instrument:
            Name of instrument as seen in the Data Dictionary (metadata).
        event:
            Unique event name, only used in longitudinal projects
        repeat_instance:
            only for projects with repeating instruments/events)
            The repeat instance number of the repeating event (if longitudinal)
            or the repeating instrument (if classic or longitudinal).
            Default value is '1'.

    Returns:
        URL of survey link requested

    Examples:
        >>> proj.export_survey_link(record="1", instrument="form_1", event="event_1_arm_1")
        'https://redcapdemo.vumc.org/surveys/?s=...'
    """
    payload = self._initialize_payload(
        content="surveyLink",
        # Hard-coded due to the nature of the response
        return_format_type="csv",
    )

    payload["record"] = record
    payload["instrument"] = instrument
    payload["repeat_instance"] = repeat_instance

    if event:
        payload["event"] = event

    return cast(str, self._call_api(payload, return_type="str"))

`export_survey_participant_list(self, instrument, format_type='json', event=None, df_kwargs=None)`

Export the Survey Participant List

!!! note The passed instrument must be set up as a survey instrument.

Parameters:

Name	Type	Description	Default
`instrument`	`str`	Name of instrument as seen in the Data Dictionary (metadata).	required
`format_type`	`Literal['json', 'csv', 'xml', 'df']`	Format of returned data	`'json'`
`event`	`Optional[str]`	Unique event name, only used in longitudinal projects	`None`
`df_kwargs`	`Optional[Dict[str, Any]]`	Passed to `pandas.read_csv` to control construction of returned DataFrame. By default, nothing	`None`

Returns:

Type	Description
`Union[List[Dict[str, Any]], str, pandas.DataFrame]`	List of survey participants, along with other useful metadata such as the record, response status, etc.

Examples:

>>> proj.export_survey_participant_list(instrument="form_1", event="event_1_arm_1")
[{'email': '',
...
'survey_access_code': ...},
{'email': '',
...
'survey_access_code': ...}]

Source code in redcap/methods/surveys.py

def export_survey_participant_list(
    self,
    instrument: str,
    format_type: Literal["json", "csv", "xml", "df"] = "json",
    event: Optional[str] = None,
    df_kwargs: Optional[Dict[str, Any]] = None,
):
    """
    Export the Survey Participant List

    Note:
        The passed instrument must be set up as a survey instrument.

    Args:
        instrument:
            Name of instrument as seen in the Data Dictionary (metadata).
        format_type:
            Format of returned data
        event:
            Unique event name, only used in longitudinal projects
        df_kwargs:
            Passed to `pandas.read_csv` to control construction of
            returned DataFrame. By default, nothing

    Returns:
        Union[List[Dict[str, Any]], str, pandas.DataFrame]:
            List of survey participants,
            along with other useful
            metadata such as the record, response status, etc.

    Examples:
        >>> proj.export_survey_participant_list(instrument="form_1", event="event_1_arm_1")
        [{'email': '',
        ...
        'survey_access_code': ...},
        {'email': '',
        ...
        'survey_access_code': ...}]
    """
    payload = self._initialize_payload(
        content="participantList",
        format_type=format_type,
    )
    payload["instrument"] = instrument
    if event:
        payload["event"] = event

    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="participantList",
        format_type=format_type,
        df_kwargs=df_kwargs,
    )

`export_survey_queue_link(self, record)`

Export one survey queue link

!!! note The passed instrument must be set up as a survey instrument. The survey queue must be enabled for the project.

Parameters:

Name	Type	Description	Default
`record`	`str`	Name of the record	required

Returns:

Type	Description
`str`	URL of survey queue link requested

Examples:

>>> proj.export_survey_queue_link(record="1")
'https://redcapdemo.vumc.org/surveys/?sq=...'

Source code in redcap/methods/surveys.py

def export_survey_queue_link(
    self,
    record: str,
) -> str:
    """
    Export one survey queue link

    Note:
        The passed instrument must be set up as a survey instrument. The
        survey queue must be enabled for the project.

    Args:
        record:
            Name of the record

    Returns:
        URL of survey queue link requested

    Examples:
        >>> proj.export_survey_queue_link(record="1")
        'https://redcapdemo.vumc.org/surveys/?sq=...'
    """
    payload = self._initialize_payload(
        content="surveyQueueLink",
        # Hard-coded due to the nature of the response
        return_format_type="csv",
    )

    payload["record"] = record

    return cast(str, self._call_api(payload, return_type="str"))

`export_survey_return_code(self, record, instrument, event=None, repeat_instance=1)`

Export a Survey Return Code for a Participant

!!! note The passed instrument must be set up as a survey instrument, which has return codes enabled.

Parameters:

Name	Type	Description	Default
`record`	`str`	Name of the record	required
`instrument`	`str`	Name of instrument as seen in the Data Dictionary (metadata).	required
`event`	`Optional[str]`	Unique event name, only used in longitudinal projects	`None`
`repeat_instance`	`int`	only for projects with repeating instruments/events) The repeat instance number of the repeating event (if longitudinal) or the repeating instrument (if classic or longitudinal). Default value is '1'.	`1`

Returns:

Type	Description
`str`	A survey return code for a specified record and data collection instrument

Examples:

>>> proj.export_survey_return_code(record="1", instrument="form_1", event="event_1_arm_1")
'...'

Source code in redcap/methods/surveys.py

def export_survey_return_code(
    self,
    record: str,
    instrument: str,
    event: Optional[str] = None,
    repeat_instance: int = 1,
) -> str:
    # pylint: disable=line-too-long
    """
    Export a Survey Return Code for a Participant

    Note:
        The passed instrument must be set up as a survey instrument, which has return codes enabled.

    Args:
        record:
            Name of the record
        instrument:
            Name of instrument as seen in the Data Dictionary (metadata).
        event:
            Unique event name, only used in longitudinal projects
        repeat_instance:
            only for projects with repeating instruments/events)
            The repeat instance number of the repeating event (if longitudinal)
            or the repeating instrument (if classic or longitudinal).
            Default value is '1'.

    Returns:
        A survey return code for a specified record and data collection
        instrument

    Examples:
        >>> proj.export_survey_return_code(record="1", instrument="form_1", event="event_1_arm_1")
        '...'
    """
    # pylint: enable=line-too-long
    payload = self._initialize_payload(
        content="surveyReturnCode",
        # Hard-coded due to the nature of the response
        return_format_type="csv",
    )

    payload["record"] = record
    payload["instrument"] = instrument
    payload["repeat_instance"] = repeat_instance

    if event:
        payload["event"] = event

    return cast(str, self._call_api(payload, return_type="str"))

Surveys

Surveys (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_survey_access_code(self, record, instrument, event=None, repeat_instance=1)

export_survey_link(self, record, instrument, event=None, repeat_instance=1)

export_survey_participant_list(self, instrument, format_type='json', event=None, df_kwargs=None)

export_survey_queue_link(self, record)

export_survey_return_code(self, record, instrument, event=None, repeat_instance=1)

`Surveys (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_survey_access_code(self, record, instrument, event=None, repeat_instance=1)`

`export_survey_link(self, record, instrument, event=None, repeat_instance=1)`

`export_survey_participant_list(self, instrument, format_type='json', event=None, df_kwargs=None)`

`export_survey_queue_link(self, record)`

`export_survey_return_code(self, record, instrument, event=None, repeat_instance=1)`