In this tutorial we will cover the use of an advanced feature, the function chips. These will allow you to modify data chips directly if they have values that are not exactly what you need them to be.
First, follow along with the following video tutorial quickly explaining function chips, then read the in depth instructions below for more information.
In depth Tutorial
There are a number of situations in which the data you import is useful but needs a little bit of tweaking to be completely useful. Currently, Adapter offers four functions that allow you to modify a data chip. The video above covers only one function, but we will cover all of them in the following sections.
This function chip helps to remedy data columns that are not dense, or in other words, columns that have blank rows. We want our statements to be as complete as possible, so in the event a row is blank, we can provide a default value to use.
In the example above we have created a minimally viable statement and have also attached the Result.success and Result.completion to it. This will produce valid statements, however if we look at our preview table, we can see that neither of these columns have a 100% data coverage.
If we go to step 3 we can see the result of this incomplete coverage.
Looking at these two statements we will notice that both of them are valid, but Row 5 contains a result component and Row 6 does not. This is because those rows were blank in Row 6 so they were simply skipped over. Whenever possible, we would like this data to be represented however, so in the case of a blank row it would be helpful to provide a default.
Let's return to step 2 and expand the advanced menu.
In this example, we will focus on the Default chip. Let us grab it and drag it up to the Result.success data chip in the palette.
Once you have dropped the function chip onto the Result.success chip you will get this dialog popup. Enter the term False as the default text. In this case, if no data is present we are going to assume that the user did not succeed the event, which is a sensible default.
If we return to step 3 once more, we will now see that every row will have Result data, whether it was blank or not.
This feature is more for personalizing your data rather than adhering to any specification. In the event you prefer having parts of your data standardized to a format (all caps, or all lowercase, etc) you can use this function.
Since this is a fairly straight-forward feature, we'll jump straight into it. For this example, we want the actor > Mbox to contain only lowercase letters.
In the example above we have already created a valid statement and have expanded the advanced tab to reveal the function chips. We are looking at the Case Change in this case, and are going to drag the chip over to the Actor.email chip.
Once we have done this, the following menu will pop up.
We can choose from three ways to change the case: lowercase, uppercase, and capitalize (first letter of every word). For this, we are just going to lowercase everything.
If we now look to our previewed output, we will notice that our actor > Mbox is completely lowercased.
This function allows you to perform a single, in-place search and replace operation onto a chip. The use of this chip is open-ended and determined by your specific needs.
Below we will go through a trivial example of this function chip.
In this situation, we have two names for verbs, either failed or passed. Let's say we decided that perhaps we would rather have the verb succeeded instead of passed.
So, let us expand the advanced tab and drag the Replace Text chip onto the Verb.id.
This will open up a dialog box.
Enter in the text you want to search for and then the replacement text, and save it. If we look at step 3, these replacements will be complete.
Our text now reads succeeded instead of passed as we wanted it to.
While the other function chips were fairly open-ended, this chip has a very specific use case. The xAPI spec has a property under result > score called scaled. This property is required to contain a value between -1 and 1 and represented a normalized value of your raw score. While this is valuable data and helps to standardize your data for analytics, it is unlikely you collect or store your data in this manner. Our normalize function can help in this case.
In this example, we have a result.score column and we are using it to represent both the raw and scaled score in our statement. When we go to step 3, we will notice this is not valid for an xAPI statement.
Our statements fail because the result > score > scaled property is falling outside of the [-1 1] range of valid scores. You could return to your file, create a new column and run a spreadsheet function to normalize that data yourself. Or, you could use the normalize function chip and let it do the hard work for you.
Above, we have expanded the advanced section and are focusing on the function tray once again. This time we are using the normalize function. Let's drag it on top of the result.score chip in the result > score > scaled property.
To normalize our data, all the function needs to know is what the possible min and max values are for the score. In this case, our score could range from -100 to 100, so that is what I entered. Hit save once your are done to save these changes.
Let's now return to step 3 to see if that fixed our problem.
As we can see, the result > score > scaled property is now properly scaled within [-1 1] and this gives us valid statements. In addition, we were able to reuse the native score field to provide a result > score > raw.
To reiterate once more, this chip has a very specific purpose that has been outlined above. This will likely be the function chip you use the least, but when you need it, this feature can be very powerful.
As Adapter is currently in Beta, this list of functions chips is definitely growing. Upon collecting feedback from users we will identify more places where we can deliver power directly into the hands of end users, so please provide feedback as you use this application.
Refer to these other resources for more information and advanced features: