Home

Madrona Portal: Survey Module (mp-survey)

This module combines with the madrona-portal tool and its additional mp-visualize and mp-map-groups modules to create and share surveys, storing the respondent's feedback on the server's database.

Creating a Survey

To create a new survey, a user must have 'administrative access' to the Django Admin Dashboard (https://your.domain.tld/django-admin).

Once logged in, you will find a "Survey" section in the dashboard's home menu:

Either click on the "+add" button next to "Surveys" or click on "Surveys" directly to open the list of all surveys, then click the "ADD SURVEY+" button in the top right corner.

You will be presented with a series of question (more detail in Survey Anatomy below). These are the main tools to control the 'meta' aspects of the survey, including setting the title and description, enabling and controlling sharing/publishing the survey, and setting start and end dates.

After that, there are a series of nested expandable forms to control the remaining aspects of the survey, including creating survey questions, adding contextual layers to the layers menu, creating scenarios, and managing planning unit-level questions and selections if your survey is spatial, and coin allocations if it is also weighted.

Publishing a Survey

Once you have created a survey, it is not immediately visible to any users. To make a survey available for respondents to take, you must associate it with one or more Groups (from mp-map-groups), and set a 'start' and 'end' date for the survey. Now, if a member of a Group that the survey is shared with logs in and opens the mapping tool (/visualize) and navigates to the MyPlanner tab, they will see a new section: "Group Surveys"

Accessing and Taking a Survey

The survey will be accessible to that user so long as:

they are logged in
the survey is 'live'
- between the start and end dates
they are a member of a group the survey is associated with.

As stated in the Publishing a Survey section, it is found in the mapping tool (/visualize) in the MyPlanner tab. All available surveys will be listed by expanding the "Group Surveys" section. This section will not appear if ANY of the above criteria are not met.

Survey Anatomy

Beyond the 'meta' information about a survey, it is comprised of two types of components:

Questions (obviously)
Map Layers for context

Survey and Survey Questions

You may have questions required to help categorize or analyze survey response types, such as identification/contact fields for who is taking the survey, which is useful if the logged in user is taking the survey on behalf of someone else, or the survey allows for multiple responses (which is not yet implemented at the time of this writing). These questions will never be repeated. These questions are separate from big picture questions about the scenario the survey is asking the respondent to describe, which may be repeated if the survey is requesting multiple scenarios (also not supported at the time of this writing). More importantly, these questions should have nothing to do with any spatial information you wish to collect -- any information that is specific to a selected area (referred to later as a 'Planning Unit') must be saved for the Planning Unit Questions section below.

You can access the survey questions form by expanding the 'SURVEY QUESTIONS' section in the Survey Form: click on '(SHOW)' next to the header if the form is collapsed (default).

Survey Question Form Fields

Text:
- The text of the question you wish to present to users
- There is a 1,024 character limit (including spaces) for this text
Order:
- The order you wish the question to appear in -- this is NOT defined by the order they appear in the form
Question type:
- Text, Number, Single-Choice, and Multiple-Choice
- More information about this in the section below Question Types
Is required:
- Specifies if a user must answer this question for their response to be saved
Collect other:
- NOT CURRENTLY IMPLEMENTED
- This will enable an 'other' option to appear in single-choice or multiple-choice questions, which will follow up with a text field to collect what is meant by 'other'.
- Until this is implemented, this can still be replicated by adding 'other' as an option for choice fields and adding a separate "Other" Text question instructing users to capture that context.
Help Text:
- If the question could benefit from extra context you can provide it here to display (in smaller font) any clarifications

Question Types

At the time of this writing, there are 4 supported question types:

Text
- A user is asked to type out an open answer to the presented question text.
- There is no enforced character limit for user responses
Number
- When a user is asked for a number
- This is useful over text when there is interest in running analysis on the response, or aggregating responses across survey responses once the survey is complete
- Users are not limited to positive integers: decimal-point answers and negatives are allowed
Single-Choice
- Users are presented with a list of pre-selected options
- Users may only choose 1
- Defining these options is handled below
- This allows for analysis/aggregation to be performed on non-numeric answers
- This is also the best way to create True/False or Yes/No type questions
Multiple-Choice
- Users are presented with a list of pre-selected options
- Users may choose as many as they wish

Defining Choice Question Options

NOTE: This section holds true for 3 different parts of the form:

Survey Questions
Scenario Questions
Planning Unit Questions

The only difference will be in how some of the options are named ('survey'/'scenario'/'planning unit').

If your question type is either Single-Choice or Multiple-Choice, you will need to define the options for the user to present from. Under every question form, there is a "SURVEY QUESTION OPTIONS" expandable form to define these.

Initially you are presented with rows to create two new options. Each row contains 3 components:

Text:
- The text of the option to be presented to the user.
Order:
- The order in which the option should appear: lowest-to-highest
Delete?
- You may click this circled-x icon to remove this entry

It is likely you will want more than two options for users to choose from. When you are ready to add more options, click the "+ Add another Survey Question Option" button below your table of options to add a row.

Layers

If you are building a spatial survey where users will indicate areas on a map and answer questions about them, it is unlikely they will come into the survey already knowing which area divisions (called "Planning Units" in sections below) that are presented to them in the survey they intend to prioritize. Instead they are more likely to know the kinds of intersecting conditions they are looking for. Being able to see these planning units on a map that also shows layers of the information they most need to make their decisions is crucial for collecting accurate data. Even if the survey is non-spatial, this context may still be incredibly valuable.

The Madrona Portal Survey Tool has a massive advantage over most other survey tools: it has a map with access to any published web map to provide context and help users answer questions in complex decision spaces. Before or during the course of taking the survey, the user can add any layer available in the Portal (via its mp-layers module) to the map from the data tab. If a web layer is available online and not included in the default options provided to all users, they can also use the layer import tool to bring in other layers they may like from the MyPlanner tab's 'User-Imported Layers' section, though they will have to interrupt their survey to toggle these layers as the survey occupies the entire 'MyPlanner' pane when active.

On top of all that, the survey administrator (likely you if you're reading this document) can also curate a list of layers that are likely to be particularly relevant to any user taking the survey!

There are two component forms to understand to add contextual layers to a survey:

Survey Layer Groups
- Used to organize the available layers into contextualize groups that can be collapsed for easy navigation
Survey Layer Orders
- Used to assign layers to those groups and organize their order

NOTE: Any layer added to a layer group and added to the map during a user's session (whether from the Survey's Layer Groups or from the Data Tab) will be removed from the map when the user completes the survey.

Survey Layer Groups

Groups are used to organize layers into contextual collections. This makes it easier to find the information a user wants, while also exposing them to related layers they may not have thought to look for.

The form is very simple:

Name:
- The name of the group (such as 'infrastructure' or 'biology')
Order:
- A numeric value to indicate which order the groups should appear (lowest-to-highest)

At least 1 group is required to add layers to your survey. You can add more groups by clicking on the "+ Add another Survey Layer Group" button seen at the bottom of the screenshot above.

Survey Layer Orders

Groups are great, but they are meaningless without Layers. This is the form used to add layers to groups -- it can be opened by expanding the "SURVEY LAYER ORDERS" section at the bottom of each "Survey Layer Group" section:

Auto Show:
- If checked, this layer will be added to the map automatically when a user begins a survey.
- This is an excellent way to display the Planning Unit definitions
Order:
- The order in which to show the layers within the group (lowest-to-highest)
Layer:
- The layer to show
- Layers are defined in the Layers module of the Madrona Planner dashboard. Creating layers is beyond the scope of this document (like WAY beyond...)

You can continue to add more layers to a group using the "+ Add another Survey Layer Order".

Scenario and Scenario Questions

A 'scenario' is the picture you are asking each survey participant to describe to you through the survey form. For example, if you are asking state governments where they most want to see seafloor surveys performed, you want them to describe this ideal future state in tangible ways so that this description can be quantified and analyzed.

Scenario Form

Much like the 'meta' questions used to define the type of survey you wish to build (before creating survey questions), the same is true for scenarios. A scenario has its own name, description, whether this is a spatial survey, and many other settings. In fact, this is the most complicated of all of the forms:

Name
- The name of the scenario.
- Can be left blank.
Order
- The numeric order this survey should appear if there are multiple surveys, from lowest to highest
- This is unused at the time of this writing as adding multiple scenarios to a survey is not yet implemented.
Description
- Any additional context about the scenario you wish to communicate to the survey respondents
PU (Planning Unit) Family
- This is required for a spatial survey.
- This will define the full list of planning units that users will be selecting from and attributing information to.
- Please review the Planning Unit Family section for more details.
User-Defined PUs (Planning Units)
- Not yet implemented
- A hoped-for future feature for surveys would be to let the user draw or define their own areas to share information about.
- Checking this box will be how that is managed in the future (in lieu of adding a Planning Unit Family)
Study Bounds
- Not yet implemented
- Defining the bounds of a survey would allow two new features:
  - Zooming to the extent of the study area when a user opens a survey
  - Only using a subset of Planning Units from a large planning unit family (e.g. only use 10km cells off the Mid-Atlantic coast from a family of PUs that span the entire Eastern Seaboard)
Selection Snapping
- Not yet implemented
- If users are selecting numerous planning units by drawing shapes, this would define whether a unit would be selected just by intersecting that drawing or being wholly within the drawn feature.
Is Spatial
- Check this box if the user will be selecting planning units and answering questions about them
Is weighted
- Check this box if this is a spatial survey AND users will be allocating coins to planning units to indicate relative value
Total coins
- The maximum number of coins a user can allocate across their selected planning units
Require all coins used
- Check this if a user's survey is not considered to be complete if they do not allocate every last coin
Min coins per PU
- The minimum number of coins a user may allocate to a Planning Unit
Max coins per PU
- The maximum number of coins a user may allocate to a Planning Unit

Scenario Questions Form

If you are asking bigger-picture questions about the scenario, perhaps even "describe in your own words your ideal future scenario where all of the seafloor surveys you most need have been conducted", this is the right place.

However, just as in the Survey Questions section you were asked to refrain from asking questions directly related to scenarios and any areas ("planning units"), it is still not time to ask questions about planning units. Currently a survey can only have one scenario, but it is hoped that limitation will be removed in the future. For now, that means there is little difference between asking Survey questions and Scenario questions beyond when/where they will appear as the user takes the survey.

Other than a few differences in naming conventions, this form is identical to the Survey Questions Form above. The form is accessed by expanding the "SCENARIO QUESTIONS" banner near the bottom of the Scenario Form screenshot.

Planning Unit and Planning Unit Questions

Planning Units

A Planning Unit is a defined area that a survey respondent will be answering questions about (in a spatial survey) and applying relative value to (coins, in a 'weighted' survey). These can come in any shape or size, from 10km grid cells across the Atlantic Seaboard to 10th-Field Hydrological Units (watersheds) in Washington state. As noted above, these may not even be pre-defined: letting users add and draw their own areas for planning units is a common method for spatial prioritization surveys (though this functionality is not yet enabled at the time of this writing).

To define the planning units for a survey in advance, you will need to create a Planning Unit Family and upload a zipped shapefile or GeoJSON of the planning unit geometries (no attributes will be kept or stored). See the Planning Unit Family section below for details.

Planning Unit Questions

If you are building a weighted spatial survey, this is likely where the bulk of your questions will live. However, there are no more meta fields: the planning units and weighting behavior were covered when defining your scenario. Other than a few differences in naming conventions, this form is identical to the Survey Questions Form above. The form is accessed by expanding the "PLANNING UNIT QUESTIONS" banner at the bottom of the Scenario Form screenshot.

Planning Unit Family

A Planning Unit Family defines all of the potential planning units you may wish to use for a survey in one umbrella so that they can be assigned to the survey in a single field. Part of creating a new Planning Unit Family is uploading a GIS file (GeoJSON or a zipped Shapefile) of the planning unit geometries you want to belong to the family.

Unlike everything else on this page, adding a Planning Unit Family (and planning units by extension) is done in a form separate from the sprawling Survey form. Just as you did when Creating a Survey, review the "Survey" section in the dashboard's home menu:

To create a new Planning Unit Family click on the "+add" button next to "Planning Unit Families" or click on "Planning Unit Families" directly to open the list of all existing families, then click the "ADD PLANNING UNIT FAMILY +" button in the top right corner.