Variables 

Overview

Variables are the fundamental data elements in Network Canvas protocols. Every piece of information you collect—from an alter's name to the strength of a relationship—is stored in a variable. Understanding variables is essential for designing effective protocols and working with your exported data.

When you create a protocol in Architect, you define variables by:

1. Choosing which entity type they belong to (ego, node, or edge)
2. Selecting a variable type (text, number, boolean, categorical, etc.)
3. Assigning an input control that determines how participants provide data
4. Optionally configuring validation rules

Variable types

Network Canvas supports several variable types, each designed for different kinds of data:

Text (String)

Text variables collect text-based responses like names, descriptions, or open-ended answers. Available input controls include Text Input (single line) and Text Area (multiple lines). Examples include alter name ("John Smith"), relationship description ("We met at work and became close friends"), and notes about an alter. In exported data, text variables appear as text strings in CSV and as text elements in GraphML.

Number

Number variables collect numerical data like ages, counts, ratings, or measurements. The available input control is Number Input. Examples include age (34), number of interactions per week (5), and years known (12). In exported data, number variables appear as numeric values suitable for statistical analysis.

Boolean

Boolean variables collect binary true/false or yes/no data. Available input controls include Toggle and Checkbox (single). Examples include lives nearby (true/false), provides emotional support (yes/no), and family member (true/false). In exported data, boolean variables appear as true/false in CSV and as boolean values in GraphML.

Categorical (Nominal)

Categorical variables collect data where options have no inherent order—responses are distinct categories. Available input controls include Radio Button Group (single selection), Toggle Button Group (single selection), and Checkbox Group (multiple selection). Examples include gender (Male, Female, Non-binary, Other), relationship type (Friend, Family, Colleague, Neighbor), and communication methods (Phone, Email, In-person, Text, with multiple possible). In exported data, categorical variables appear as one column per option, with true/false values, whether participants can select one option or several.

Ordinal

Ordinal variables collect data where options have a meaningful order or ranking. Available input controls include Likert Scale, Radio Button Group, and Toggle Button Group. Examples include closeness (Not close, Somewhat close, Very close, Extremely close), contact frequency (Never, Rarely, Monthly, Weekly, Daily), and agreement (Strongly disagree, Disagree, Neutral, Agree, Strongly agree). In exported data, ordinal variables can be treated as ordered categories for ordinal analysis.

Scalar (Continuous)

Scalar variables collect continuous numerical data along a scale. The available input control is Visual Analog Scale (VAS). Examples include emotional closeness, trust level, and relationship strength. Rather than a numeric range, you give the scale a label for each end (such as "Not at all close" and "Extremely close"), and the participant positions a slider between them. The response is recorded on a normalised scale from 0 to 1, so in exported data scalar variables appear as decimals suitable for continuous statistical analysis.

Date

Date variables collect specific dates. The available input control is Date Picker. Examples include date of birth, last contact date, and when a relationship began. In exported data, date variables appear as date values in standard format (YYYY-MM-DD).

Layout (Coordinates)

Layout variables store the x/y position of nodes on Sociogram interfaces. There are no input controls for layout variables, as they are automatically captured from Sociogram interactions. Examples include node position on Sociogram and spatial layout coordinates. In exported data, layout variables appear as X and Y coordinate values (normalized 0-1 or pixel coordinates based on export options).

Location

Location variables store the geospatial area a participant selects for an alter on the Geospatial interface. Like layout variables, a Location variable has no input control of its own; although it appears in the variable type list, there is little reason to add one there on its own. In practice Architect creates one when you configure the "Selection Variable" of a Geospatial stage (you can pick an existing Location variable or create a new one inline). The selected area is recorded against the GeoJSON shapefile that defines the map.

How variables work

Variable creation

You create variables when configuring Interfaces in Architect:

1. Name Generators: Create variables for alter attributes (name, demographics, characteristics)
2. Forms: Create variables for any entity type (ego, alter, or edge attributes)
3. Categorical/Ordinal Bins: Create categorical or ordinal variables
4. Sociogram: Automatically creates layout variables for node positions

Variable scope

Variables are scoped to entity types.

Ego variables collect data about the participant, such as age, gender, and demographics, as well as network-level measures and session metadata. There is one value per interview for each ego variable.

Node variables collect data about alters, including alter attributes (name, age, relationship type) and characteristics and demographics. There are multiple values per interview (one per alter) for each node variable.

Edge variables collect data about relationships between alters, including relationship attributes (strength, frequency, type) and tie characteristics. There are multiple values per interview (one per edge) for each edge variable.

Variable reuse

Once you create a variable, you can use it across multiple stages in your protocol. This provides consistency (same variable definition everywhere), efficiency (define once, use many times), and data quality (consistent data structure). Note that changes to a variable (type, input control, validation) apply to all uses of that variable throughout the protocol.

Variable persistence

Variables persist throughout the interview:

• Values set on early stages are available on later stages
• You can use skip logic to conditionally show stages based on variable values
• You can use network filtering to show only entities with specific variable values

Encrypted variables

A variable can carry an encrypted flag, which marks its values for on-device encryption so that they cannot be read by the researcher. This is not a general per-variable control: it is not exposed in the variable editor. Instead, you add an Anonymisation interface to your protocol and select which node attributes to encrypt in its Encrypted attributes section. Encrypted values are stored only in encrypted form, and are never included in exports in readable form. See the Anonymisation interface documentation for details.

Creating variables

In forms

When creating a field on a form:

1. Click Select attribute, then choose an existing attribute or type a new name (use descriptive names: close_friend, contact_frequency) and choose Create new attribute called “…”.
2. Select an input control—this sets the variable type
3. Configure any control-specific options
4. Set validation rules if needed

In categorical/ordinal bins

When configuring bins:

1. Name the variable (e.g., relationship_strength)
2. Define the categories or order levels
3. The variable type is automatically set to categorical or ordinal

In Architect, the answer options of a categorical or ordinal attribute are edited directly under the attribute you chose, wherever you choose one: a bin prompt, a form field, a tie-strength prompt or a Network Composer row. They are saved by the same button that saves the rest of the prompt or field. A boolean attribute's two labels are edited the same way. Option labels accept bold and italic text, which participants see as emphasis, and nothing else — a label can't contain headings, links or lists. An attribute whose options belong to an interface is shown read-only, with a note saying why.

Automatic variables

Some variables are created automatically:

Layout variables: Created when you add a Sociogram interface

• Store x/y coordinates of node positions
• Named by the Sociogram stage

Location variables: Created when you configure a Geospatial interface

• Store the geospatial area selected for an alter
• Created (or selected) via the stage's "Selection Variable"

System variables: Network Canvas creates these automatically

• networkCanvasUUID - Unique identifier for each entity
• networkCanvasEgoUUID - Unique identifier for ego
• Timestamps and session metadata

Variable naming best practices

A variable's name is how it appears in the codebook, and it becomes the column name in your exported data. This section covers what a name can contain, the names Architect refuses because they would clash in exported data, and some advice on choosing names that are easy to analyze.

What a name can contain

Names can be written in any language, and they can include spaces and punctuation. All of these are valid variable names:

• close_friend
• género
• 关系类型
• contact frequency (per week)

The same freedom applies to the names of node types and edge types, and to the values of categorical and ordinal options. There are only two limits on what any of these can contain. A name:

• can't be empty
• can't contain tabs, line breaks, or other invisible control characters, nor the special codes U+FFFE and U+FFFF, which don't appear in ordinary text. These characters usually arrive when you paste text copied from another program.

A variable's name also can't be the same as the name of another variable of the same node type, edge type, or ego, however it is capitalized: Age and age count as the same name.

Architect tidies each name as you save it. It removes any spaces from the start and end, and it stores accented letters in one consistent form (Unicode NFC), so a name typed on two different keyboards is saved the same way.

The column headings of a roster file work differently: Architect refuses a heading that starts or ends with a space, rather than removing the spaces. See Column headings in Working with Roster Data for when this happens.

Names that would clash in exported data

Most variables are exported as a single column named after the variable, but two types are exported as several columns:

• A categorical variable gets one column for each option, named variable_option. A variable support with the options emotional and financial gets the columns support_emotional and support_financial.
• A layout variable gets one column for each coordinate: _x and _y in CSV files, _X and _Y in GraphML files, and _screenSpaceX and _screenSpaceY when screen layout coordinates are exported.

This means two different names can still produce the same column. Architect checks for this whenever you name a variable, add an option, or change an option's value, and it explains which column would clash. As with duplicate names, capitalization is ignored. The check covers CSV and GraphML, including the screen layout columns, because you choose names long before you choose export options.

Architect refuses a name or option in each of these situations:

These are the built-in column names that variables can't use, in any capitalization. Option columns and layout columns can't use them either.

Protocols created before Architect made these checks open and run as before. If one of them has two variables that write the same column, the export renames one of the columns and warns you. See Column names that clash.

Use descriptive names

Good examples:

• close_friend (clear meaning)
• contact_frequency (describes what's measured)
• provides_emotional_support (unambiguous)

Poor examples:

• var1 (meaningless)
• q3 (not self-documenting)
• test (unclear purpose)

Use consistent conventions

Choose a naming style and stick to it:

• snake_case (recommended): contact_frequency, close_friend
• camelCase: contactFrequency, closeFriend
• PascalCase: ContactFrequency, CloseFriend

Keep names concise

Good: age, gender, rel_type, freq Too long: participants_relationship_type_classification_scheme

Plan for data analysis

Your CSV files keep every name as you wrote it, in any language. Some analysis software handles spaces and punctuation in column names less smoothly, though:

• Base R's read.csv replaces spaces and punctuation in column names with dots unless you add check.names = FALSE. See Opening CSV files.
• In R, a column name that contains a space has to be quoted with backticks, as in alters$`close friend`. In pandas, it can only be used with brackets, as in alters["close friend"].
• Hyphens can be read as minus signs in formulas, and some software doesn't accept a name that starts with a number, such as 1contact.
• A name that starts with =, +, - or @ gets an apostrophe in front of it as a CSV column header, so that spreadsheet programs don't run it as a formula. See Why some values start with an apostrophe.
• Some statistical packages have stricter rules for variable names than Network Canvas, and may rename columns when you import a file.
• GraphML attribute names can't contain spaces or most punctuation, so the GraphML export replaces those characters with _. See GraphML attribute names.

If you want names that you never need to quote in R or Python, use only letters, numbers, and underscores (snake_case), and start each name with a letter. It also helps to:

• prefer short names, because some statistical packages limit their length
• avoid abbreviations that will be unclear months later

Working with variables

Viewing all variables

Use the Codebook in Architect:

1. Open the Codebook in your protocol
2. View all variables organized by entity type
3. See where each variable is used
4. Delete unused variables

Modifying variables

You can change the input control (if compatible with variable type), validation rules, options for categorical variables, and the attribute's name. You cannot change the variable type, which is set when first created with an input control.

To rename an attribute, click the pill of the attribute a section has selected — the one shown under Change attribute in a prompt, form field, or other attribute picker — or focus it and press Enter or Space. (Pills shown elsewhere, such as in the attribute search results or in a rule's summary, are labels rather than controls; in the Codebook, use the edit control on the attribute's own row instead.) A box opens holding the current name; type the new name and click Save Changes. The new name follows the same rules as any other name: see What a name can contain and Names that would clash in exported data. Cancelling, pressing Escape, or clicking away keeps the old name. Stages that use the attribute keep using it under its new name, but remember that the name becomes the column name in exported data.

Changes you make to the codebook while a stage is open — creating an attribute, renaming it, or editing its options or validation rules — are written to the codebook straight away. They are kept even if you then cancel your edits to the stage, because an attribute belongs to every stage that uses it rather than to the stage you are editing.

To change the variable type, create a new variable with the desired settings, replace the old variable with the new one on all stages, and delete the old variable from the codebook.

Deleting variables

You can only delete unused variables:

1. Open the Codebook
2. Find variables marked "not in use"
3. Delete unused variables

Note: Variables in use cannot be deleted—remove them from all stages first.

Variables in exported data

CSV export structure

Each CSV file starts with identifier columns that link the files together, followed by one or more columns for each variable. Most variables get one column. A categorical variable gets one column per option, named variable_option and holding true or false, so the gender variable below becomes three columns.

Ego file: one row per interview, with the session details and then the ego variables

networkCanvasEgoUUID,networkCanvasCaseID,networkCanvasSessionID,networkCanvasProtocolName,sessionStart,sessionFinish,sessionExported,APP_VERSION,COMMIT_HASH,networkCanvasFinishOutcome,age,gender_female,gender_male,gender_non_binary
abc123,case_001,sess456,My Study,2025-01-15T10:30:00.000Z,2025-01-15T11:15:00.000Z,2025-01-16T09:00:00.000Z,9.0.0,1a2b3c4,completed,34,false,true,false

Alter files: one row per alter, with its alter variables

nodeID,networkCanvasEgoUUID,networkCanvasUUID,name,age,close_friend
1,abc123,xyz789,John,32,true
2,abc123,uvw456,Sarah,29,false

Edge files: one row per edge, with its edge variables. from and to hold the nodeID of the two alters it connects.

edgeID,from,to,networkCanvasEgoUUID,networkCanvasUUID,networkCanvasSourceUUID,networkCanvasTargetUUID,relationship_strength,frequency
1,1,2,abc123,edg001,xyz789,uvw456,strong,weekly

For a full reference mapping every variable type to its exported CSV columns and GraphML attributes—along with advice on analyzing each type—see the Export Data Dictionary.

Variable naming in exports

Variable names in your protocol become column names in exported data:

• close_friend variable → close_friend column
• Categorical variables → one column per option, named variable_option with true/false values
• Layout variables → columns named after the variable with _x and _y suffixes (e.g. my_layout_x and my_layout_y)

CSV files use each name exactly as it appears in the codebook, including any spaces, punctuation, or letters from other languages. GraphML attribute names can't hold spaces or most punctuation, so a variable named contact frequency (per week) becomes contact_frequency__per_week_ in a GraphML file, and the original name is kept alongside it. See GraphML attribute names.

Architect refuses names that would give two variables the same column, including names that only become the same once an export writes them, such as close friend and close_friend in GraphML (see Names that would clash in exported data). If a protocol created before that check has such a clash, the export renames the later column with a _2 suffix (or _3, and so on) and shows a warning. When two names only become the same in GraphML, the name that was already valid keeps it, and the other gets the suffix.

Common patterns

Demographic variables (ego)

age: Number (Number Input)
gender: Categorical (Radio Button Group)
education: Ordinal (Radio Button Group)
zip_code: Text (Text Input)

Alter identification

name: Text (Text Input, required)
relationship_type: Categorical (Radio Button Group)
age: Number (Number Input)
lives_nearby: Boolean (Toggle)

Relationship characteristics

closeness: Ordinal (Likert Scale)
contact_frequency: Ordinal (Radio Button Group)
support_type: Categorical (Checkbox Group, multiple)
relationship_duration: Number (Number Input)

Support networks

provides_emotional_support: Boolean (Toggle)
provides_practical_support: Boolean (Toggle)
provides_financial_support: Boolean (Toggle)
support_frequency: Ordinal (Radio Button Group)

Troubleshooting

Variable not appearing in codebook

Cause: Variable created but not saved Solution: Ensure you saved the stage configuration

Can't change variable type

Cause: Variable type is set when first created Solution: Create new variable with desired type, replace old one

Need to rename a variable

Solution: Click the attribute's pill and type the new name. See Modifying variables.

Architect won't accept a variable name

Cause: The name contains a tab, line break, or other invisible character (often from text pasted from another program), is already used by another variable, or would write the same column as another variable or a built-in column in exported data Solution: Read the message under the name field, which says which rule the name breaks. Retype the name rather than pasting it, or choose a name that doesn't clash. See Variable naming best practices.

Variable shows "not in use" but can't delete

Cause: Variable is used somewhere in protocol Solution: Check all stages, remove all uses before deleting

Variable values not in export

Cause:

• Variable not assigned on any stage
• Forms not completed during interview
• Validation prevented completion

Solution:

• Verify variables are used on stages
• Check that stages were shown (not skipped)
• Review validation rules

Categorical variable showing weird codes in export

Cause: Using underlying values instead of labels Solution: Check your analysis software's import settings, ensure proper factor/categorical encoding

Related concepts

• Input Controls - Choose input controls that set variable types
• Field Validation - Add validation rules to variables
• Forms - Create forms that collect variable data
• Codebook - View and manage all variables in your protocol
• Data Export - Understand how variables appear in exported data
• Interfaces - Different Interfaces for collecting different types of variables
• Skip Logic - Use variable values to control stage flow
• Network Filtering - Filter entities based on variable values

Next steps

Now that you understand variables, you can:

1. Plan your variable structure before building your protocol
2. Choose appropriate variable types and input controls for your research questions
3. Review the Codebook guide to manage variables effectively
4. Learn about Input Controls to choose the right controls
5. Understand Data Export to prepare for analysis