This article follows on from the introductery Skills article, and discusses:
- Skills and the Displayr Cloud Drive
- Skill inheritance / multiple versions of the same skill
- Worked examples
Skills and the Displayr Cloud Drive
When you save a skill, it's saved into a folder in the Displayr Cloud Drive as a text file with file extension .QSkill.
You can manually create text files and save them into the Displayr Cloud Drive, and they will be available in the Skills menu (if they have an appropriately formatted name, file extension, and are in an appropriate folder). This is discussed in more detail below in Worked examples > Brand awareness.
Skill inheritance / multiple versions of the same skill
You can have two or more versions of the same skill. For example, you may have a general data cleaning skill in the home folder, and the a special version just applicable to one client in the folder that contains that client's work. When there are multiple skills with identical names, Displayr works as follows:
- It gives precedence to a skill in the same folder as the document.
- It then looks in the next folder "up".
- It keeps going up until it gets to the home folder.
Consequently, if you save a folder into your home drive, this skill is available to all users in all documents, but you can have different versions for different folders based on where it is saved.
Worked examples
These examples build on from the worked example in Skills, so make sure you've read it first.
Brand awareness
- The skill calculates brand awareness - top of mind and total spontaneous awareness.
- The name of the skill is brand-awareness.
- The box below shows the contents of a .QSkill file. The file name was brand-awareness.QSkill, where the name of the skill is the file name (excluding the file extension).
- The When to use field is referred to in the file as the argument-hint.
- If you read down to the Text Categorization section, it explicitly tells Displayr which menu option to use (Data Source > + > Text Categorization). If, instead, the skill told it to "create a text categorization," we are leaving the AI to decide which of many dozens of alternative approaches to use.
- At the very end, it's referring to another skill called add-page-with-purple-bar-chart. In general, it's a good idea to create skills that refer to other skills, rather than to have the same code repeated in lots of skills.
---
description: "Calculates Spontaneous Awareness and Top of Mind Awareness (TOMA — the first brand named) from open-ended brand-recall survey text."
argument-hint: "Use this whenever the user asks to calculate spontaneous awareness, unaided awareness, top-of-mind awareness, TOMA, first-mention, or 'which brand do people name first' — including when they describe that goal without using these exact terms. Do not use for non-awareness data, or when the user explicitly wants a 'List of Items' categorization."
---
# Find the spontaneous awareness data
If the user has mentioned a specific variable or variable set, use it. Otherwise, find a variable set that measures spontaneous awareness for brands. The variable set will be:
- One or more text variables.
- Contain brands
- Ask about awareness
- Ask the user if it's not clear.
# Identify the Brand List
There are only two was to do this:
- If the user has given a Brand List when requesting this skill and asked you to use it, then use that as the Brand List. Only use an existing Brand List if you've been told to do it.
- Otherwise:
- Read through the spontaneous awareness data (do not use any)
- Identify all the brands. When doing this, fix and ignore any spelling issues (i.e., if there are multiple spellings of a brand, just list the correct name).
- Collate an exhaustive Brand List
# Decide whether to calculate Top of Mind Awareness or Spontaneous Awareness.
Top of Mind Awareness: The first brand a person mentions when asked to list brands they've heard of.
Spontaneous Awareness: All the brands a person mentions when asked to list brands they've heard of.
If the user explicitly requests one or the other, then we will calculate that.
Otherwise, ask the user.
# Create the Text Categorization
Create a new Text Categorization variable set using "Data Sources > + > Text Categorization".
- Using the spontaneous awareness variable set identified earlier.
- If calculating Top of Mind Awareness, create with only one theme per respondent. Otherwise, create with multiple themes per respondent.
- Themes: the Brand List
- Prompt to use when classifying for Top of Mind Awareness:
"Your job is to classify open-ended text responses from a survey question asking people about which brands they can remember.
Classify as follows:
- First brand mentioned matches a theme → that theme
- First brand mentioned doesn't match a theme → Other
- No brand / blank / irrelevant response / don't know → NA
Respondents will not write brand names consistently. Treat a response as
matching a theme whenever it clearly refers to that brand despite differences in:
- spelling, including obvious misspellings and phonetic spellings (e.g. "Volkswagon", "Maccdonalds")
- spacing, hyphenation, and punctuation (e.g. "Coca Cola", "Coca-Cola", "cocacola")
- capitalization and leading/trailing whitespace
- common abbreviations, nicknames, and shortened forms (e.g. "Maccas" for McDonald's, "Coke" for Coca-Cola)
- plurals and possessives
Be careful not to confuse parent and sub-brands. E.g., 'Diet Coke' should not be classified as 'Coke' if there is a 'Diet Coke' theme. Prefer the more specific theme.
Match to the single most likely theme. Do not force a match: if a
brand is mentioned that you cannot confidently link to any theme, apply the Other
rule; if no brand is mentioned, apply the NA rule.
The themes are arbitrary, there is no preference given to the order that the themes appear."
- Prompt to use when classifying for Spontaneous Awareness:
"Your job is to classify open-ended text responses from a survey question asking people about which brands they can remember.
Classify as follows:
A brand matches a theme → that theme
A brand is mentioned that doesn't match a theme → Other
No brand / blank / irrelevant response / don't know → NA
Respondents will not write brand names consistently. Treat a response as
matching a theme whenever it clearly refers to that brand despite differences in:
- spelling, including obvious misspellings and phonetic spellings (e.g. "Volkswagon", "Maccdonalds")
- spacing, hyphenation, and punctuation (e.g. "Coca Cola", "Coca-Cola", "cocacola")
- capitalization and leading/trailing whitespace
- common abbreviations, nicknames, and shortened forms (e.g. "Maccas" for McDonald's, "Coke" for Coca-Cola)
- plurals and possessives
Be careful not to confuse parent and sub-brands. E.g., 'Diet Coke' should not be classified as 'Coke' if there is a 'Diet Coke' theme. Prefer the more specific theme.
Match a brand to the single most likely theme. Do not force a match: if a
brand is mentioned that you cannot confidently link to any theme, apply the Other
rule; if no brand is mentioned, apply the NA rule.
Each response can simultaneously belong to multiple themes (brands).
The themes are arbitrary, there is no preference given to the order that the themes appear."
# Name the variable set
1. Start by choosing "Top of Mind Awareness" or "Spontaneous Awareness" as appropriate.
2. If the user provides some kind of rationale for which brands to use, append something relevant to the variable set name (e.g., "Spontaneous Awareness - New Brands").
3. If the name has already been used for a variable set, increment by appending integers until you find a unique one (e.g., Top of Mind Awareness 1, Top of Mind Awareness 2, etc.).
4. Set the Label property of the variable set just created to the new name.
# Tabulate
Run the add-page-with-purple-bar-chart skill using the variable set we just created.
Applying a template via QScript
This skill is a super-advanced example, designed for people that are confortable writing code. A few things to callout:
- The When to use (argument-hint) field was left blank. You don't need to fill this field in. But it can help.
- This skill is running QScript code. The code was written by chat.
- The QScript code runs a template. (A much easier way to run a template via a skill is just to tell the agent (e.g., "Apply the 'Purple Bar Chart.viz.QTemplate' template").
---
description: "Adds a new page, creating a summary table, and showing that as a purple bar chart."
argument-hint: ""
---
1. Ask the user what variable set they wish to use. Or, if they've provided one already, us it.
2. In the QScript code block below, replace VARIABLE_SET_NAME with the name of the user's variable set.
3. Run the QScript code using runHandCodedQScript().
```
// References
var data_to_use = "VARIABLE_SET_NAME";
var report = project.report;
var data_file = project.dataFiles[0];
// Add a Title Only page
var page = report.appendPage("Title Only");
page.name = data_to_use;
// Add table of Education
var edu_q = data_file.getQuestionByName(data_to_use);
var t = page.appendTable();
t.primary = edu_q;
// Apply visualization template to turn table into a chart
t = t.applyTemplate("Purple Bar Chart.viz.QTemplate");
```