I am copy pasting here my design reflections from September 2021. The final design may have deviated a bit, but it seems nice to keep a copy of it in or issue history:
DESIGN
Based on the users and their criteria as discussed in #4, I would like to propose the following app design. The current version of the app already has most of the code components needed for this, the main task is now to connect them.
Wizard interface
The GUI should take the user step by step through the process. A big dashboard with many buttons will overwhelm the user and introduce risk that user overlooks important decisions. The wizard will go through the following stages:
Ask user what data types they want to process, and use this to ask about their research interests. In that way we can deduce what software tools will be needed and in what order. So, this gives us the main pipeline components. I have now implemented this, see demo at bottom of this overview2.
For each of the tools in the pipeline ask user to select relevant input files. The GUI will know which files are relevant. So, a user not interested in sleep assessment will not be asked about the availability of a sleep diary.
For each of the tools in the pipeline give user the option to specify parameters deemed relevant, e.g. non-wear detection criteria.
Buttons to start each stage of the pipeline, and once processing is done give user the option to inspect output.
I think it would be useful to allow the user to log out and log in at a later time without killing the processing of the data. However, I am not sure if this is easy in UCloud. Maybe that is something we can work on after the first release of the app.
Software architecture
As discussed:
One repository for the Shiny app (HabitusGUI).
One repository with docker files that install the shiny app and all the tools (GGIR, PALMSpy, etc).
Once launched the docker image will expose only the Shiny app to the user, which in turn talks to the tools.
Tool integration
To ease expanding the Habitus app with new tools, we expect the following items to be provided per tool:
Installation instruction for local installation without docker.
Integration test to check that installation instruction works.
A pipeline function that applies the tool to input data and stores the output in a user-specified location. This function should allow for configuration file and other arguments, and check that input is valid.
User-interface requirements file1, which specifies the UI elements needed for updating parameters. For example, a radio button to let user choose which detection algorithm to use.
Example configuration file
Documentation about how configuration file can be specified, accessible as text via browser.
Example data file or snapshot of a data file to help the user understand what the expected input is.
List of research goals for which the tool is suitable, we will present them with an optional list.
Does the tool depend on the output from another tool used in the GUI? If yes, does that other tool have to be configured in a specific way for this tool to work?
1 Fields of this UI requirements field may include:
Field
Description
UI element type
Numeric field, radio button, check box, ...
Default value for the UI field
For example, Europe/Amsterdam
Variable name
Object name used to pass it on to the function (item 1 above), e.g. tzone
Label name
Label to be displayed in the GUI, e.g. Timezone.
Documentation
Additional documentation to be displayed in the GUI, e.g. Select the timezone in which the data was collected.
Guiding and educating the user
Each input field of the GUI will be accompanied with a simple jargon free instruction. If jargon is necessary we will explain it.
For the input fields related to specific software tools, e.g. GGIR, the maintainer and possibly an experienced user are expected to help us identify the key parameters the user may want to modify. This is part of the 'tool integration' process as discussed above.
Users who want to learn more:
If the user wants to learn how to modify the configuration file, a simple tutorial may be difficult to organize because configuration files can involve dozens of parameters. As an example, when I give a training about using GGIR it usually takes 4.5 hours to go through all the relevant aspects of configuring GGIR, often tailored to the specific needs of the person I am training. Transforming this learning process to a concise number of text fields in the app feels difficult.
Another challenge with educating users about all the detailed parameters that can be set with a configuration file is that it would double the effort to write and maintain such documentation, because each software tool will also have its own documentation that needs maintenance. Double documentation introduces risk of inconsistencies.
As a solution I propose that we direct the user to example configuration file(s) and point them to the documentation of the software tool that should cover documentation about the configuration file(s).
2 Demo of first page
These are screenshots of the current version of the app. Text phrasing and typos will be easy to fix.
As data types are selected checkboxes with potential research interests become visible
Once the GPS and GIS boxes are ticked 'Trips' and 'Behaviour environment relation' are added to the optional research interests
Once research interests are selected a pipeline is proposed to the user:
Once research interests are expanded with trips and Behaviour environment relation the pipeline is update with PALMS and PALMSplus.
USERS AND THEIR CRITERIA
We discussed this before, but it may be good to create an overview of expected user types and their criteria on the Habitus app.
End-user1:
Owns accelerometer, GIS, and/or GPS data.
May not know anything about how to analyse these data.
Wants support tailored to their research interests and data, and does not want to be bothered with unrelated questions.
Wants to be able to run a standard analysis using default settings without too much hassle.
Wants to learn how to tweak the analysis, e.g. with a configuration file.
1 We previously talked about planning for beginner- and advanced user modes. Now I reflect more on it I am not sure how an advanced user would differ from a beginner user. The advanced user knows better how to modify the configuration file, but after that the process should be identical. Therefore, aiming for a single version of the app that suits both will reduce software complexity and by that maintainability. Note that a software developer, like me, who wants to investigate a problem will most likely prefer to work with the software directly outside the app. For this, all we need is a RStudio environment and a Jupyter notebook, which UCloud already facilitates.
Maintainers of software tool used by Habitus app:
Prefers to avoid duplication of their code and documentation, because that will introduce risk for consistency and double maintenance effort.
May prefer minimal involvement in the integration of their software in the Habitus app. So, ideally we should be able to integrate future releases of their software without their help.
Habitus app maintainer:
Code structure should be easy to expand with new tools and not tight to just GGIR, PALMS and PALMSplus.
In collaboration with the user it should be easy to pinpoint where in the code a problem occurred, and how it can be reproduced in isolation from the rest of the pipeline.
App should have as many automated checks as needed to prevent the most obvious beginner mistakes, this to avoid being overwhelmed with many help requests.
I am copy pasting here my design reflections from September 2021. The final design may have deviated a bit, but it seems nice to keep a copy of it in or issue history:
DESIGN
Based on the users and their criteria as discussed in #4, I would like to propose the following app design. The current version of the app already has most of the code components needed for this, the main task is now to connect them.
Wizard interface
The GUI should take the user step by step through the process. A big dashboard with many buttons will overwhelm the user and introduce risk that user overlooks important decisions. The wizard will go through the following stages:
I think it would be useful to allow the user to log out and log in at a later time without killing the processing of the data. However, I am not sure if this is easy in UCloud. Maybe that is something we can work on after the first release of the app.
Software architecture
As discussed:
Tool integration
To ease expanding the Habitus app with new tools, we expect the following items to be provided per tool:
1 Fields of this UI requirements field may include:
Guiding and educating the user
Each input field of the GUI will be accompanied with a simple jargon free instruction. If jargon is necessary we will explain it.
For the input fields related to specific software tools, e.g. GGIR, the maintainer and possibly an experienced user are expected to help us identify the key parameters the user may want to modify. This is part of the 'tool integration' process as discussed above.
Users who want to learn more:
If the user wants to learn how to modify the configuration file, a simple tutorial may be difficult to organize because configuration files can involve dozens of parameters. As an example, when I give a training about using GGIR it usually takes 4.5 hours to go through all the relevant aspects of configuring GGIR, often tailored to the specific needs of the person I am training. Transforming this learning process to a concise number of text fields in the app feels difficult.
Another challenge with educating users about all the detailed parameters that can be set with a configuration file is that it would double the effort to write and maintain such documentation, because each software tool will also have its own documentation that needs maintenance. Double documentation introduces risk of inconsistencies.
As a solution I propose that we direct the user to example configuration file(s) and point them to the documentation of the software tool that should cover documentation about the configuration file(s).
2 Demo of first page
These are screenshots of the current version of the app. Text phrasing and typos will be easy to fix.
As data types are selected checkboxes with potential research interests become visible
Once the GPS and GIS boxes are ticked 'Trips' and 'Behaviour environment relation' are added to the optional research interests
Once research interests are selected a pipeline is proposed to the user:
Once research interests are expanded with trips and Behaviour environment relation the pipeline is update with PALMS and PALMSplus.
USERS AND THEIR CRITERIA
We discussed this before, but it may be good to create an overview of expected user types and their criteria on the Habitus app.
End-user1:
1 We previously talked about planning for beginner- and advanced user modes. Now I reflect more on it I am not sure how an advanced user would differ from a beginner user. The advanced user knows better how to modify the configuration file, but after that the process should be identical. Therefore, aiming for a single version of the app that suits both will reduce software complexity and by that maintainability. Note that a software developer, like me, who wants to investigate a problem will most likely prefer to work with the software directly outside the app. For this, all we need is a RStudio environment and a Jupyter notebook, which UCloud already facilitates.
Maintainers of software tool used by Habitus app:
Habitus app maintainer: