Setting up elements

This topic describes setting up categories for an individual variable. To set up a shared category list that can be used with more than one variable, see Setting up shared category lists.

For each category in a categorical variable:

2 Give the element a name. The convention is that this is the same as the element text but with invalid characters removed and spaces replaced with the underscore (_) character. However, you can give the element a shorter name if you prefer, provided it is unique within the Elements collection. If your data source has names for its categories, it makes sense to use the same names here.

3 Populate the element's labels. Typically, only one text is stored for an element in each language (in the Question user context and Label label type). However, alternative texts can be stored if required (for example, a shorter text in the Analysis user context for use in tables). For a guide to setting up additional label texts for different user contexts and label types, see Setting up basic questions.

4 Set the element's type. Typically, this is mtCategory, which indicates that the element corresponds to one of the possible responses in the category list. However, other element types can be used to indicate that it is a special element used during analysis. For a guide to element types, see ElementTypeConstants in the MDM Object Model Reference.

5 If necessary, set the element's flag, to indicate whether it is a special category (for example, Don't Know, Refused to Answer, No Answer, and so on). Some of these flags (such as flOther) are set automatically by the MDM and cannot be set manually. For a guide to category flags, see CategoryFlagConstants in the MDM Object Model Reference.

6 For Other Specify categories, you also need to create a text variable to hold the open-ended responses and to add it to the variable's HelperFields collection. For more information, see Setting up helper fields.

The MDM assigns a unique value to each unique element full name in the MDM Document. The unique values are called mapped category values (sometimes shortened to mapped values). Element full names must be unique within a question, but the same full name can be used in different questions. For example, categories called Yes and No can be used in several questions, and will have the same mapped value in each one.

MDM automatically creates the mapped value when the element is first accessed in a unlocked version and when a version is locked, MDM automatically assigns mapped values to all elements for which they have not already been assigned. However, you can assign values to all elements in an unlocked version by using the CategoryMap.AutoAssignValues method. You can also define a specific mapped value for individual elements manually using the CategoryMap.Add method, provided the mapped value has not been assigned already and the same numeric value has not been used for another category.

The MDM automatically creates an ElementInstance object to map a category to its native value, which is a DataSource-specific value that you can optionally set up to identify the categories in the proprietary data. For more information, see How should a CDSC return categorical data?.