Today we’ll introduce you to a great feature that was recently added to the SAMI trial tools: sessions!
What is a session?
A session is a way for a trial administrator to record metadata along with trial data. For example, Andrea’s trial includes several participants all sending data from Simband to the trial. As the administrator, Andrea may not only want to receive the device data, but also include additional information on the participant and the context (“going for a run on a cold rainy day”). Context is, after all, where Simband’s powerful sensors excel alongside SAMI!
We are actively using the sessions feature in this way with Simband. Below we’ll show you how to use the Trials Admin portal UI to create your own session. Here’s a tutorial video:
Note that we have also documented the sessions APIs that allow you to programmatically create, start and end a session, as well as record and retrieve data associated with it. We used the same APIs to build the sessions functionality you see in the portal.
Creating a trial session
If you have a trial with at least one participant, you can click the link to the lower left of the trial dashboard to create a session for this trial.
The first step of creating a session is choosing a participant and the device. The menus auto-populate with the available trial participants and devices.
The next step is key—this is where you can populate the session with relevant metadata. The UI here allows you to fill in a key and its value; for example, “gender” and “male”, respectively. However, a more efficient way to approach this might be to create metadata rules that you can apply straightaway to other sessions instead of manually entering keys and values each time. Metadata rules are a template of key titles and value types:
When you apply this template to a new session, you will be able to fill in the corresponding values.
Managing your sessions
Back on the session dashboard, you will see that your newly created session is listed in the Ongoing Sessions tab.
Take note of the controls under the Actions and Data columns. The pencil icon allows you to add a start and/or end date for the session and further edit the metadata. Clicking the stopwatch icon is how you stop the session.
Stopping the session is also possible in the Data Visualization view, which you access using the magnifying glass icon under Data. You will also be prompted to select data fields to display in real-time. Read more about using Data Visualization.
Finally, the clipboard icon reveals a JSON snippet that you can use in your scripts to fetch data from various sources. For example, the JSON includes the session ID, which you can use to fetch a session from the sessions API; and the export ID, which you can use to fetch an export via the exports API. (Note that the export ID is meant to eliminate re-export of the same data segment, and will be “null” for your first export.)
Ending a session
When you stop the session, it moves from the Ongoing to the Previous Sessions tab.
Here you see an option to export your session data for review or further analytics, a feature we covered here. You can also access Data Visualization to get another view of your historical session data.
The sessions feature makes running complex trials a snap. Are you using the SAMI portals to conduct your own research? Let us know!