Type: Package
Title: Read Data from 'LimeSurvey'
Version: 1.2.0
Description: Read data from 'LimeSurvey' (https://www.limesurvey.org/) in a comfortable way. Heavily inspired by 'limer' (https://github.com/cloudyr/limer/), which lacked a few comfort features for me.
License: MIT + file LICENSE
URL: https://gitlab.com/REDS1736/ipanema
Encoding: UTF-8
Imports: base64enc, DBI, dplyr, httr, jsonlite, magrittr, RMySQL
RoxygenNote: 7.3.2
Depends: R (≥ 2.10)
NeedsCompilation: no
Packaged: 2025-05-09 15:59:32 UTC; max
Author: Maximilian Hagspiel [aut, cre, cph]
Maintainer: Maximilian Hagspiel <maxhag@mailbox.org>
Repository: CRAN
Date/Publication: 2025-05-09 16:20:02 UTC

base64_to_df

Description

Convert a base64 representation of a CSV table into a 'data.frame' object.

Usage

base64_to_df(x)

Arguments

x

The base64-encoded CSV string

Value

A 'data.frame' object containing the data from 'x'.

connect_to_limesurvey

Description

Connect to 'LimeSurvey' instance via the RPC and a direct MySQL connection. Store the RPC session key in ‘options(’limesurvey_session_key')'. Store the MySQL connection object in ‘options(’limesurvey_mysql_connection')'. Store the RPC URL in ‘options(’limesurvey_api_url')'.

Usage

connect_to_limesurvey(
  api_url,
  limesurvey_username,
  limesurvey_password,
  mysql_host,
  mysql_port,
  mysql_dbname,
  mysql_table_prefix,
  mysql_username,
  mysql_password
)

Arguments

api_url

URL to the 'LimeSurvey' RPC, e.g. 'http://localhost/index.php/admin/remotecontrol'

limesurvey_username

Username for the 'LimeSurvey' API

limesurvey_password

Password for the 'LimeSurvey' API

mysql_host

Hostname of the MySQL server used by 'LimeSurvey'

mysql_port

Port on which the MySQL server listens for connections

mysql_dbname

Name of the database on the MySQL server which is used by 'LimeSurvey'

mysql_table_prefix

Prefix for all table names, e.g. "lime_"

mysql_username

Username for the MySQL server

mysql_password

Password for the MySQL server

Value

No return value, called for side effects

Examples

# This example assumes a locally hosted `LimeSurvey` instance using a locally
# hosted MySQL server
## Not run: 
connect_to_limesurvey(
  api_url = 'https://localhost/index.php/admin/remotecontrol',
  limesurvey_username = 'admin',
  limesurvey_password = '1234admin',
  mysql_host = '127.0.0.1',
  mysql_port = 3306,
  mysql_dbname = 'limesurvey',
  mysql_table_prefix = '',
  mysql_username = 'lime',
  mysql_password = '1234lime'
)

## End(Not run)

fix_column_data_types

Description

Freshly exported data has all item-data columns as type "character". This function converts these columns to ideal types (e.g. integer). Currently simply converts all multiple-choice columns to integer. Future task: Add conversion to other data types as needed.

Usage

fix_column_data_types(df_in)

Arguments

df_in

The 'data.frame' object to fix.

Value

A 'data.frame' object containing the data from 'df_in' but with fixed column data types.

get_answer_options

Description

Get the answer options to a question with pre-defined answer options (e.g. a multiple choice question).

Usage

get_answer_options(question_code)

Arguments

question_code

Code by which to identify the question. Follows a dot-based naming scheme: <group title>.<subquestion title>.

Value

'data.frame' object with the columns 'code' and 'answer' in which each row represents one answer option where 'code' is the encoded value (as found in datasets exported by 'get_survey_data()' and 'answer' is the answer option text as seen by survey users).

Examples

# This example assumes a locally hosted `LimeSurvey` instance using a locally
# hosted MySQL server.
# On this `LimeSurvey` instance, there is a survey with the ID 123456.
# In this survey, a multiple-choice question identified by the code "bdi.01"
# is used.
# For this question, this example retrieves the possible answer options.
## Not run: 
connect_to_limesurvey(
  api_url = 'https://localhost/index.php/admin/remotecontrol',
  limesurvey_username = 'admin',
  limesurvey_password = '1234admin',
  mysql_host = '127.0.0.1',
  mysql_port = 3306,
  mysql_dbname = 'limesurvey',
  mysql_table_prefix = '',
  mysql_username = 'lime',
  mysql_password = '1234lime'
)

answer_options <- get_answer_options("bdi.01")

## End(Not run)

get_question_text

Description

Get the question text (e.g. "How have you been feeling?") to a question in the dataset.

Usage

get_question_text(question_code)

Arguments

question_code

Code by which to identify the question. Follows a dot-based naming scheme: <group title>.<subquestion title>.

Value

'character' object containing the question text

Examples

# This example assumes a locally hosted `LimeSurvey` instance using a locally
# hosted MySQL server.
# On this `LimeSurvey` instance, there is a survey with the ID 123456.
# In this survey, a multiple-choice question identified by the code "bdi.01"
# is used.
# For this question, this example retrieves the question text which was shown
# to the user when answering the questionnaire.
## Not run: 
connect_to_limesurvey(
  api_url = 'https://localhost/index.php/admin/remotecontrol',
  limesurvey_username = 'admin',
  limesurvey_password = '1234admin',
  mysql_host = '127.0.0.1',
  mysql_port = 3306,
  mysql_dbname = 'limesurvey',
  mysql_table_prefix = '',
  mysql_username = 'lime',
  mysql_password = '1234lime'
)

q_text <- get_question_text("bdi.01")

## End(Not run)

get_sql_varname

Description

Get the internal SQL field name (e.g. "697929X4X21") to a question from a specific survey in the dataset.

Usage

get_sql_varname(question_code, survey_id)

Arguments

question_code

Code by which to identify the question. Follows a dot-based naming scheme: <group title>.<subquestion title>.

survey_id

Survey-ID of the survey from which to select the question.

Value

'character' object containing the field name

Examples

# This example assumes a locally hosted `LimeSurvey` instance using a locally
# hosted MySQL server.
# On this `LimeSurvey` instance, there is a survey with the ID 123456.
# In this survey, a multiple-choice question identified by the code "bdi.01"
# is used.
# For this question, this example retrieves name of the SQL table field in
# which `LimeSurvey` internally stores the responses to this question.
## Not run: 
connect_to_limesurvey(
  api_url = 'https://localhost/index.php/admin/remotecontrol',
  limesurvey_username = 'admin',
  limesurvey_password = '1234admin',
  mysql_host = '127.0.0.1',
  mysql_port = 3306,
  mysql_dbname = 'limesurvey',
  mysql_table_prefix = '',
  mysql_username = 'lime',
  mysql_password = '1234lime'
)

q_varname <- get_sql_varname("bdi.01", 123456)

## End(Not run)

get_survey_data

Description

Get collected data from a specific survey on the connected 'LimeSurvey' instance. Includes complete and incomplete cases! Returns 'NULL' if no data has been collected in this survey.

Usage

get_survey_data(survey_id, completion_status = "all")

Arguments

survey_id

ID of the survey from which the collected data shall be extracted. 6-digit integer.

completion_status

'complete' = Return only complete cases; 'incomplete' = Return only incomplete cases; 'all' = Return both.

Value

A 'data.frame' object containing the survey data. Column names follow a dot-based naming scheme: <group title>.<subquestion title>. 'NULL' if no data has been collected.

Examples

# This example assumes a locally hosted `LimeSurvey` instance using a locally
# hosted MySQL server.
# On this `LimeSurvey` instance, there is a survey with the ID 123456.
## Not run: 
connect_to_limesurvey(
  api_url = 'https://localhost/index.php/admin/remotecontrol',
  limesurvey_username = 'admin',
  limesurvey_password = '1234admin',
  mysql_host = '127.0.0.1',
  mysql_port = 3306,
  mysql_dbname = 'limesurvey',
  mysql_table_prefix = '',
  mysql_username = 'lime',
  mysql_password = '1234lime'
)

df_data <- get_survey_data(123456)

## End(Not run)

get_survey_id

Description

Get numerical LimeSurvey ID of the survey with the given title.

Usage

get_survey_id(survey_title)

Arguments

survey_title

TItle of the survey. String.

Value

An integer Survey ID which can be used as a parameter in 'get_survey_data()'

Examples

# This example assumes a locally hosted `LimeSurvey` instance using a locally
# hosted MySQL server.
# On this `LimeSurvey` instance, there is a survey with the title 'mysurvey'.
## Not run: 
connect_to_limesurvey(
  api_url = 'https://localhost/index.php/admin/remotecontrol',
  limesurvey_username = 'admin',
  limesurvey_password = '1234admin',
  mysql_host = '127.0.0.1',
  mysql_port = 3306,
  mysql_dbname = 'limesurvey',
  mysql_table_prefix = '',
  mysql_username = 'lime',
  mysql_password = '1234lime'
)

survey_id <- get_survey_id('mysurvey')
df_data <- get_survey_data(survey_id)

## End(Not run)

limesurvey_api_call

Description

Perform a call to the 'LimeSurvey' RPC API.

Usage

limesurvey_api_call(method, params = list(), ...)

Arguments

method

Name of the API method to call. A complete list of methods can be found here: https://api.limesurvey.org/classes/remotecontrol_handle.html

params

Parameters to pass to the API

...

Additional parameters passed from above

Value

A list containing the de-serialized response.

wipe_survey_data

Description

Delete all data collected by this survey.

Usage

wipe_survey_data(survey_id)

Arguments

survey_id

ID of the survey from which the collected data shall be deleted. 6-digit integer.

Value

Nothing. Function is called for side effects on SQL table.

Examples

# This example assumes a locally hosted `LimeSurvey` instance using a locally
# hosted MySQL server.
# On this `LimeSurvey` instance, there is a survey with the ID 123456.
## Not run: 
connect_to_limesurvey(
  api_url = 'https://localhost/index.php/admin/remotecontrol',
  limesurvey_username = 'admin',
  limesurvey_password = '1234admin',
  mysql_host = '127.0.0.1',
  mysql_port = 3306,
  mysql_dbname = 'limesurvey',
  mysql_table_prefix = '',
  mysql_username = 'lime',
  mysql_password = '1234lime'
)

wipe_survey_data(123456)

## End(Not run)