Survey Import: Qualtrics, SurveyJS, LimeSurvey, XLSForm, REDCap, Beiwe and Network Canvas

New in v2.12.0

potato import turns a questionnaire built in another tool into Potato survey pages: the questions, the pages, and the show/hide logic, translated into Potato's conditional questions and page rules.

The format is detected from the file, and -f chooses it explicitly. None of these files holds responses, so the import moves the instrument and not the data collected with it.

Import into a new project

potato import -i screener.qsf -o my-study/
python potato/flask_server.py start my-study/config.yaml -p 8000

The survey pages go in my-study/surveys/, one JSON file per page. config.yaml lists them in phases.order before an annotation phase with a placeholder question and three placeholder items, which you replace with the real task.

Import into an existing project

potato import -i exit_survey.lss --into my-study/config.yaml --survey-slot poststudy --prefix exit_

The pages go in surveys/ beside that config, and a merged copy is written as config.with-exit_survey-exit.yaml, with the report in IMPORT_REPORT.exit_survey-exit.md. The original config is not changed.

--prefix renames every imported question and page. Use it when question names would clash with the project's own, since the import stops on a clash. The import also stops rather than replace files an earlier import wrote, so edits made to an imported survey are not overwritten.

The merged copy differs from the original in more than the new pages. If the config does not set export_include_phase_data, the copy sets it to true so that the survey answers are exported, and a comment at the top of the copy says so. Survey answers can hold personal data, so set it to false to leave them out of exports. Comments in the original are not kept, and YAML lists are rewritten in block style.

What carries over from every format

• question wording (HTML is reduced to text), choices, and required questions;
• pages, in order;
• show/hide logic on questions and pages, translated to display_logic and page show_when, including nested AND, OR and NOT;
• choice order randomization (randomize_order) and question order randomization (randomize_questions) where the source has them.

Answers to choice questions are stored as the option text, so the translated logic compares against option text, not the source's codes.

Everything the importer could not translate is listed in IMPORT_REPORT.md with where it was and why, and the first ten are printed. A logic rule that contains anything untranslatable is reported whole, and the question is left always visible rather than given part of its rule.

Qualtrics

Each block is a page, and each page break inside a block starts another. Trash blocks are skipped.

• Questions: multiple choice (single, multiple, dropdown, NPS), Matrix Likert (as multirate), text entry (single line, multi-line, number validation as number, forms as one text question per field), sliders, rank order (ranking), constant sum (constant_sum) and descriptive text (pure_display). "Other" choices with a text box get a free-text field.
• Logic: display logic with Qualtrics' precedence (AND before OR within a condition set, and between If, AndIf and ElseIf sets), on selected choices, text-entry values, slider values and selection counts.
• Survey flow: branches become page rules, with nested branches combined by AND. A randomizer that shows all of its blocks becomes a counterbalance group. A randomizer that shows one of several embedded-data assignments to one field becomes a between-subjects factor under conditions, and logic on that field tests condition.<field>. End of Survey inside a branch, and skip logic to the end of the survey, become exit_when.
• Reported, not imported: Loop & Merge (the block is imported once), piped text, matrix-cell logic, "is displayed" conditions, choice-level display logic, quotas, web services, authenticators, scoring, custom validation, request-response (soft required), JavaScript, and the question types Potato has no equivalent for (heat maps, hot spots, file upload, signature, side-by-side, timing, meta info).

Coming from Qualtrics maps the rest of a Qualtrics study to Potato.

SurveyJS

• Elements: text (number inputs as number), comment, radiogroup, checkbox, dropdown, tagbox, boolean, rating, ranking, matrix, multipletext (one text question per item), html and slider. Panels are flattened into the page, and a panel's visibleIf applies to each question in it.
• Logic: visibleIf on questions, panels and pages, including anyof, allof, contains, empty, {q.length} selection counts, and and, or and !. A complete trigger becomes an exit_when on the page that asks the last question it tests.
• Reported, not imported: enableIf, requiredIf, choicesVisibleIf, validators, default values, calculated values and expression questions, setvalue, skip and runexpression triggers, dynamic matrices and panels, file and signature questions, and logic that calls functions.

LimeSurvey

Both file layouts import: older exports with a language column on each row, and exports from DBVersion 400 on, with the text in *_l10ns tables. The survey's base language is used unless --survey-language says otherwise. Question groups become pages, in order, and group relevance becomes the page's show_when.

• Questions: list (radio, dropdown, with comment), 5-point, yes/no, gender, multiple choice, the array types (as multirate), short and long text, numerical, multiple numerical and multiple short text (one question per subquestion), ranking and text display.
• Logic: ExpressionScript relevance on question codes, subquestion codes and SGQA names, with is_empty(), count() over a multiple-choice question, and and, or and !, plus the older conditions table.
• Reported, not imported: date, equation, file upload and dual-scale questions; hidden questions; validation (preg, em_validation); minimum and maximum answers; array filters; randomization groups; quotas; assessments; piped text; and if(), regexMatch() and .shown in logic.

XLSForm: ODK, KoboToolbox, SurveyCTO and Ona

ODK shows one question per screen unless a group asks for more, and Potato puts a page's questions together, so the import uses the form's own grouping. Each begin_group with appearance: field-list or table-list is one page, and the questions between such groups share a page. Another group's relevant is applied to every question inside it, and its label becomes a heading. For a form with several label columns, such as label::English and label::French, --survey-language French picks one, and otherwise the form's default_language is used.

Reported, not imported: geopoints and other location types, date and time, photos, audio, video, barcodes and files; calculate and hidden fields and logic that uses them; repeats (their questions are imported once); constraint, choice_filter, default, read_only and conditional required; and external choice lists. An .xls file needs the xlrd package, or save it as .xlsx.

REDCap

Each instrument (form) becomes a page, in the order the dictionary lists them, and section headers become headings on the page.

Reported, not imported: calculated fields and logic that uses them, file and SQL fields, validation types Potato does not check (dates, emails and phone numbers become plain text with a format hint), other action tags, piped values, and logic that uses functions (datediff, sum), events ([event][field]) or form status. REDCap's longitudinal events and repeating instruments have no Potato equivalent.

Potato is not a clinical data capture system and has no audit trail of the kind REDCap provides for regulated studies. Keep identifiable health data in REDCap, and use Potato for the annotation and the questions around it, such as clinicians labeling notes or images.

Beiwe

Each survey in the export becomes a page. Info text, slider, radio button, checkbox and free-response (numeric, single line, multi-line) questions import, and display_if logic translates, with radio answers tested by position and checkbox answers by membership. Date and time questions, audio surveys, schedules and timings are reported, because Potato has no survey scheduling, and so is partial randomization.

Network Canvas

An ego form or information stage becomes a survey page, and the network stages for one node type become one ego_network question on one page, with its name generators, name interpreters, dyad and tie-strength censuses, and sociogram. CSV or JSON roster assets become the name generator's roster. Ego skip logic becomes show_when, and a skip to the end of the interview becomes exit_when on the page before, with the finish screen's text as the message.

Network stages for one node type share a page, so they cannot be skipped one by one, and a network stage that came after other pages moves ahead of them. The import reports each move. Node and edge filter rules, alter edge forms, narrative and geospatial stages, date and time variables, and media items are reported and not imported. The Ego Networks page has the stage-by-stage mapping.

Further Reading

• Coming from Qualtrics - A Qualtrics study's features mapped to Potato
• Multi-Phase Workflows - Survey pages, conditional questions and phase order
• Experiment Flow - Conditions, page rules, screen-outs and counterbalancing
• Importing Projects - Annotation formats, whole projects and other imports
• Survey Instruments - Published questionnaires by name

For implementation details, see the source documentation.