Working with Roster Data 

What is a roster?

A roster is a list where each row can potentially become a node in a network. This list might consist of students in a classroom, workers in an office, or people in a team sport. Rosters can also include people mentioned in previous surveys by a specific individual, lists of words related to one's occupation, or any item where it is useful to nominate members of that list in Network Canvas. Commonly, rosters are used in whole network studies since you can merge together all of the ego-alter nominations to create a whole network. Each person in the whole network would make their nominations to others and then the researcher could combine these.

Above we noted rosters of 'people mentioned in a previous survey'. Because a roster belongs to the protocol, every participant interviewed with that protocol sees the same roster — Network Canvas does not support rosters that are specific to an individual participant.

Rosters in Network Canvas

In a Network Canvas interview session, when a person is nominating nodes we have the ability to bring nodes in from a side panel. Typically this side panel would include 'people already mentioned'. However, we can also bring in nodes from a pre-defined list. Below we discuss:

• how to create this roster list,
• how to add this list to an existing protocol,
• how to display the roster in an interview,
• how to combine rosters with side panels and additional variables (the 'alter pool'),
• issues with potential name collisions in Interviewer,
• and, finally, some tips for using rosters in sociocentric studies.

A roster in Network Canvas exists at the protocol level. That is, a protocol is used to collect cases, each one representing a participant. Since every case starts an interview session with the same protocol, every case has access to the same roster. The roster is added to your protocol in Architect and becomes one of its resources, so it travels inside the .netcanvas file that is opened in Interviewer.

How to create a roster

A roster is a list of potential nodes. To avoid confusion, the elements of this list will be called 'items' or roster items because they are not yet nodes in any given interview. This list of items should be prepared outside of Network Canvas in a spreadsheet program and exported as a special kind of file type: csv or comma-separated values.

Below is an example of a table:

Here is what the table looks like when exported to CSV

name, var1, v_2, v3a
Alice, 30, True, "Yes it's the case"
Barb, 25, False, "You can include strings!"

Considerations for formatting the CSV file

The comma-separated values format is more of a loose set of conventions than a strict standard. This means you could accidentally create a CSV that will not open correctly in Network Canvas. Below are some key considerations for your CSV files:

• The CSV file should have a header row for variable names.
• The first column should have the column header as name. This is what the participant will see when the roster item becomes a node.
• The remaining columns represent additional variables. For example, there could be a column for "club_member", "age", "profile page", etc... These variables can be useful when initially displaying a roster in an interview. They are also 'passed through' so that any data export from Network Canvas that includes these roster items as nodes will also include these columns as variables.
• Since CSVs use commas to separate columns, this means that if you want to have a column with a comma, such as an additional column for city and country (e.g., "Toronto, Canada") then the CSV needs to wrap Toronto, Canada inside of quotations so that it knows that it is a literal comma and not a column separator.
• Fortunately, if you edit a table of data in a spreadsheet program such as Microsoft Office or OpenOffice Calc, when you export that spreadsheet as a CSV it takes care of the issues with quotes and commas for you. We therefore do not recommend creating CSVs in programs like TextEdit or Notepad since they do not manage these small formatting issues.
• Blank lines are ignored, so an empty line between rows or at the end of the file does no harm.
• Even if the CSV is valid, some characters can't be used in it. The column headings become variable names, so they follow nearly the same rules as any other variable name. See Column headings and Values below.

Note: We expect the first column to be the name of the roster item with a column called name. However, these items do not need to be people. Recall that ontological flexibility is one of the design principles of Network Canvas. Thus, you could augment a study with a roster of words representing emotions, concepts, books, places, etc...

Column headings

Column headings can be written in any language and can include spaces and punctuation, so género (gender in Spanish), club member and 年龄 all work. As with any variable name, a heading:

• can't start or end with a space
• can't contain tabs, line breaks, or other invisible control characters

See What a name can contain for the full rules. When you type a variable name, Architect removes any spaces from its start and end for you. It can't do this for a heading in your file, because the interview reads each heading from the file as it is, and a heading with a space at either end would never match a variable. So Architect refuses that heading instead. In practice:

• Spaces around a heading. Network Canvas ignores spaces before and after a heading that isn't in quotation marks, so these headings work. A heading in quotation marks keeps its spaces, so one written as " age" in the file is refused.
• Accented letters. Some programs, especially on macOS, store an accented letter such as é as two characters: a plain e followed by an accent. Architect accepts a heading saved either way, and the column still matches a variable with the same name. It refuses a file with two headings that are the same name written these two ways, because only one of the two columns could fill that variable.
• Empty headings. A column with an empty heading is named after its position, such as field3 for the third column. Give every column a heading, and delete any empty columns at the end of the sheet.

Avoid two headings that differ only in capitalization, such as Name and name: Architect treats variable names that differ only in capitalization as the same name, so the two columns are easy to confuse.

Architect Classic is stricter. If you use it, start each heading with a letter, and use only the letters A–Z and a–z, numbers, and underscores. For example, género won't work in Architect Classic, but genero will.

Values

The values in your roster can be any text, in any language, so you do not need to reformat a name like "Verónica" or "王芳". A cell can contain commas, quotation marks, tabs and line breaks, as long as the cell is wrapped in quotation marks (spreadsheet programs do this for you when they save a CSV file).

A cell can't contain other invisible control characters. They can't be stored in exported GraphML files, so Architect refuses a roster that contains them. See If Architect refuses your roster.

If Architect refuses your roster

Architect checks a roster when you add it to your protocol, and explains what it found if it can't use the file. The most common problems are:

• A column heading can't be used as a variable name. Look for a heading in quotation marks that starts or ends with a space, or one that spans two lines because a new line was typed inside the heading cell. Fix the heading in your spreadsheet and save the CSV file again.
• The file contains a character that can't be used. This is an invisible control character, in a cell or in a heading. These characters can't be seen, and usually arrive in text pasted from other software, such as a PDF, a word processor, or a database export.
• Some rows have a different number of columns. Make each row match the header row. This usually means a value containing a comma was not wrapped in quotation marks, or the header row has an extra comma at the end.

When a file contains a character that can't be used, the message says where Architect found it first, and how many other places have the same problem. Because the character is invisible, the message names it by its Unicode code point, such as U+0007:

Row 5 of the “notes” column contains a character that can’t be used (U+0007). Delete it from the file, then import the file again. The same problem appears in 2 other places in the file.

Rows are numbered the way a spreadsheet numbers them, with the header row as row 1, so you can go straight to the row in your spreadsheet. A character in a heading is reported by the column's number, counting from 1 on the left. In a JSON roster, the message names the node by its position in the file's list of nodes, counting from 1, and the attribute that holds the character. If the character stops the file from being read at all, the message gives the line of the file instead.

To remove invisible control characters, open the file in a spreadsheet program and use its CLEAN function, which Microsoft Excel, Google Sheets and LibreOffice Calc all provide:

1. In an empty column, enter =CLEAN(C2), replacing C2 with the cell Architect named.
2. Copy the result, and use Paste Special to paste it over the original cell as values only.
3. Delete the extra column, and save the file as CSV again.

CLEAN also removes any tabs and line breaks from the cell. If Architect still refuses the file, delete the cell's contents and type them again by hand.

Adding the roster to a Network Canvas Interview

Once you are satisfied with your roster, you can add it to a Network Canvas protocol from within Architect. Choose the version of Architect you are using below — the screenshots and version-specific notes update to match.

You can add the roster through the Resource Library, which is available from the protocol overview screen of any protocol you are editing.

In Architect, your protocol — including any roster resources you add — is saved automatically in your browser's library as you work, and the roster is embedded into the .netcanvas file when you download the protocol.

You can also add the roster when you are creating a roster name generator. Below we walk through the steps of adding it to a name generator and we will add the roster as we go along. We will use a simple roster which includes five members of the cartoon television show, "The Simpsons", but you should be able to follow by analogy for a roster of your own making. The example CSV is available here.

Selecting the Name Generator Interface

To use a roster, you should select the interface "Name Generator for Roster Data". Give the stage a name (such as roster_01) and then create or select a node type. In the example, we have created a node type called "person" and so we will choose this. Then the program asks for "Data Source for Roster". If you have already uploaded the CSV to the Resource Library it will be available to select. Otherwise, you can upload it now.

Before you select the roster it is useful to inspect it to see that it has formatted correctly. Each roster resource has a preview button (an eye icon). Clicking on that will show the CSV that has been uploaded.

With the simpsons-roster you can observe that there is an empty cell for occupation for Maggie. This shows the data was correctly formatted and the columns are all properly aligned.

Formatting the display of the roster

Once you have selected a roster the next three items allow you to customize the look of the roster item in Interviewer. Roster items are displayed as cards rather than nodes. To nominate a roster member, the participant drags its card into the node panel, which turns it into a node and removes the card from the list. For a full description of how participants nominate roster members, see the Name Generator for Roster Data documentation.

By default, the cards will display the name of the roster item. However, you can add additional details on the card by turning on 'card display options'. This will then allow you to select from the additional columns of the CSV to be shown below the name. The left hand drop down allows you to choose the column from the CSV and the right hand item allows you to give that variable a different label. So in the simpsons-roster example, while the CSV had a column called gender (in lower case) on the card we will write Gender to be displayed.

Since a roster might have a large number of people to scan, you can also enable the cards to be sorted by some value. So if we add occupation, then in the interview the participant can sort the roster by occupation.

Finally, you can permit participants to search through the roster items using a search box. Selecting name and keeping the accuracy low means that people can find others by typing characters close to the person's name if not exactly.

In a protocol written in more than one language (see Translating Your Protocol), the labels given to card details and sort options are translated like any other text, but the roster's values are not. A roster is a resource, and its contents are the same in every language. Where participants will read values from the roster, such as occupations or course titles, check that participants using each of the protocol's languages will understand them.

Prompting for a roster item

Much like in other name generator interfaces, in order to select roster items the interface needs a prompt. This could be as simple as "Please select the people you know" however, we strongly encourage researchers to consider using common prompts or ones that relate carefully to a research question. You can use multiple prompts on the same interface.

Remember that you can use multiple prompts on the same interface but without adding additional variables you will not be able to determine which prompt elicited which node.

Considering additional prompt variables: What is an alter pool?

A roster item can only be added to the interview once (or more strictly, once per node type per interview). This is consequential if you have multiple prompts that are not mutually exclusive. For example, imagine asking people to nominate classmates they study with. Then with a second prompt one might ask about classmates they knew before this current year. What about someone who is both? This is where we can think conceptually of an 'alter pool' and then draw upon this alter pool across prompts.

In order to manage cases where alters could qualify for multiple prompts, it is useful to do two things:

• Use the 'assign additional variables' feature when creating a prompt.
• Use the 'already mentioned' panel in the interview.

When you assign an additional variable with a prompt it means that not only will that prompt create a node, but it will assign some additional data. Usually we use a boolean variable per prompt. So if you have a prompt for classmates who study together then you should also assign an additional variable 'study_together' and set it to True. Then do the same for the prompt about known before this year. When you look at your data later on, you will have two additional columns. The people nominated on the study_together prompt will have True in that column and the people nominated on the known_before prompt will have True in that column.

Since you can only turn a roster item into a node once that means that if people were created in the first, study_together prompt we need an additional way to include them in the known_before prompt. This is why we use a side panel. Side panels are available in the Name Generator (using forms) and Name Generator (using quick add) interfaces.

With a Name Generator (using quick add), we can nominate new nodes with the new node button in the lower right. But on the left hand side we can have a side panel. In fact we can have two - one for people already nominated who are now in the alter pool and one for the remaining roster items who have not yet been nominated.

We recommend that you add all the nodes you can to the alter pool before adding additional details so that you can add these details to all the nominated nodes rather than zigzagging through the protocol. This is because all stages draw from the same alter pool if they use that type of node. Imagine the following scenario: the participant adds nodes on stage 3, adds some detail on stage 4 such as how close ego is to alter, and then adds more nodes on stage 5. These newly added nodes will be available if you go back to stage 4. Also note that the roster list does not change once it is in Interviewer. So all the data that you add about a node from a roster will be available when you export your case, but it will not be associated with that roster item in subsequent interview cases.

How large is too large for a roster?

The Name Generator for Roster Data is a single interface that adapts how roster members are presented to the size of your roster. A small roster displays cards for every member, which the participant can scan and sort. With a larger roster, the participant instead uses the search box to locate members before any cards are shown. Very large rosters are supported — we have tested a 60,000 item roster with success — but loading and search will slow down considerably at that scale, so test your protocol on your intended field devices. See the roster size guidance in the interface documentation for details.

Potential pitfall: Rosters and Name Collisions

Concerning rosters, there are a handful of situations in Network Canvas that can lead to improper data if not considered fully. These issues mainly concern the fact that a node in Network Canvas is labeled by the name variable. So when the participant is linking nodes or assigning additional data if there are two people with the same value for name it can be difficult to distinguish them. Below are two examples and some proposed workarounds:

Collision type 1. Collisions within the roster list itself.

Imagine you have a roster with two people named Kwame. One is Kwame Kenyatta and the other Kwame Nkrumah. If the participant knows both of these people, then their alter pool will have two Kwames in there and the participant will not be able to distinguish them later on. While the roster card could show their surname, the node icon will just say "Kwame" for both. This is referred to as a name collision.

Internally, the program will have assigned each of these nodes a unique UUID, but the respondent will not be able to determine which is which.

Potential solution: When importing a roster, Network Canvas does not check that the name column contains only unique items. However, you can do this when you are preparing your roster. One way to do this is to copy the name column to a blank sheet, select it, and choose "Data" - "Data Tools" - "Remove Duplicates" in Excel (in Calc, choose "Data" - "More Filters" - "Standard Filter" and tick "No duplications"). If the copied list becomes shorter, some names appear more than once. Don't delete the repeats from your roster, because two different people can share a name. Instead, make each name unique. One way to do this is to create a new name variable that is a composite of first and last names. This can be done by hand or by using a formula in Excel.

We do not recommend editing the name in Network Canvas after it has been created both for technical reasons but also because you run the risk of not being able to tell that this is the same Kwame or Kwame_Nk from the roster when comparing across people. Recall that with a roster we typically want to merge data across participants to see who nominates whom.

Collision type 2. Collisions because there is already a node with that name

The second collision type happens when the duplicate name appears because the participant nominates someone outside of the roster with the same name. Imagine that we have one screen with a roster where the person nominates "Kwame" and then nominates a different Kwame using a "Name Generator (using quick add)" or "Name Generator (using forms)". Network Canvas will not alert you that there is already a node named Kwame in the alter pool. This situation should be managed by a trained interviewer and the participant should be encouraged to use unique names.

Remember, if the participant creates a new node with a duplicate name and they want to delete that node this can be done by dragging on the node and a trash can will appear. Drag the node into the trash can and create a new node with a more unique descriptive name.

Tips for rosters in sociocentric studies

A sociocentric study is one where you are interested in the connections between people within a given network boundary. To start simple, imagine we are only interested in ego-alter ties. That is, we are not focusing on a classmate's impression of whether two other people are friends. We simply want to have people nominate their peers. This can then be converted into a whole network as a matrix using some data wrangling. We do not show such wrangling here, but given past experience we can show some steps to make this process easier.

Recall that an adjacency matrix for a network has rows and columns. The rows represent the participants' data and the columns are the targets (i.e. the people that the participants nominated). Since it is a sociocentric study, the rows and the columns should have the same names. In the following simple table, we see a classroom with four students. 'Alice' nominates 'Bob' and 'Cam' as friends. 'Dot' nominates everyone as a friend, while 'Bob' and 'Cam' only nominate each other. The resulting matrix would look like the following:

In the case of a roster in Network Canvas, each participant would contribute a row. You will notice that the diagonals have - in them. This is because conceptually we would not think that people can nominate themselves in this sort of work (though that is research-question-specific).

To collect this sort of data in Network Canvas we can use a roster and only collect nominations from the participants. However, we would like to have the participant identify themselves in the roster so that they are not available for subsequent questions. To do this we can use several features of Network Canvas in tandem:

1. We can create an 'identify yourself' stage with a single prompt, and set the stage's minimum and maximum number of alters to 1.
2. We can attach an additional variable called is_ego and set it to True for that one node.
3. Because roster items become nodes only once, ego will then not be listed on subsequent roster prompts.
4. However, ego is still in the alter pool, so any time we want to do something with the alters, such as ask for data on frequency of communication, we need to filter out ego, which we can do with stage level filtering and our is_ego variable.

You can find a protocol here which has all of these features included. It has the small roster with Alice, Bob, Cam, and Dot but you can replace this with your own roster and modify it for your needs.