= PerfectFit

== Goal-setting dialog for physical activity with the virtual coach Jody
In this dialog with the virtual coach Jody, the user sets a SMART long-term goal for running or walking. The dialog was developed for a study on using personalized vicarious experiences to motivate users during a goal-setting dialog ([https://doi.org/10.1007/s10916-022-01899-9 see paper]) as part of the Perfect Fit project ([https://perfectfit-research.com/en]). The original Rasa-based implementation of the virtual coach can be found [https://doi.org/10.5281/zenodo.6647381 here].

== Technical details


The system contains two parts:

* [source:PerfectFit/Web Web Component]. This presents the user with web (html) pages that form the user interface to the dialog. This artifact has the name "chatserver".
* [source:PerfectFit/Dialog Dialog Component]. This is is the core of the application: it handles all the dialog. This artifact has the name "movingdialog".

== The Web Component
The entire Web Component is standard technology based on Apache Tomcat. It consists of 2 html pages, each containing a bit of javascript:

1.  A questionnaire page. This is a standard web form where the user can enter his characteristics (or use the default).
2. The dialog page. This part shows the dialog on a web page, styled closely to the original chatbot, and looks like WhatsApp. It communicates with the server to communicate with the Dialog Component to determine the dialog flow.

=== questionnaire page. 
The Questionnaire form is a webpage form to inquire the user's characteristics. 
The entire form (including some javascript) is in [source:PerfectFit/Web/src/main/webapp/form.html form.html] in the [source:PerfectFit/Web Web] project.
This webpage presents the user with a standard web form with a number of questions that characterise him. He can answer by clicking buttons and dragging sliders. 

After the user presses the button to complete the form, the javascript code collects the form information into a query string which is sent to the dialog page.


==== User Characteristics
The form determines the following parameters that define the user's characteristics:

||parameter name||contents||
||godin_activity||godin value, a single number 0, 1 or 2 where higher means the user does more and/or more strenuous exercise during a week. ||
||exercise_se||exercise_se value in [0,100] where larger means the user can walk/run longer per week. ||
||exercise_identity||exercise_identity  a value in [0,4] where  higher means the user describes sees/describes himself as more physically active ||
||extraversion||extraversion value in [0,6] where higher means users rank themselves higher on an extraverted and reserved scale   ||
||ttm_pa||level of actual physical activity in the last months, or planned by the user ||
||openness||openness value in [0,6] where higher means user rank themselves higher on an openness and conservative scale ||
||sitting_weekend||the number of hours the user spends sitting during the weekend ||
||age||age in years||
||household_income||the household income in british points per year||
||household_size||household size in number of people||

All these values are non-normalized raw values from the form. E.g. age is the real age in years.  

=== dialog page
The dialog page is on [source:PerfectFit/Web/src/main/webapp/chat.html chat.html] in the [source:PerfectFit/Web Web] project. This page presents the user with a whatsapp-like page that closely resembles the original dialog look and feel. 

The page shows the stimulus text from the dialog system as a chatbot that types text to the user.

When it's the turn of the user, he can type text or click a button, depending on the question from the dialog system.

== The Dialog Component
The dialog component contains a number of components:
* The dialog specification which is a json file describing all states that can occur in the dialog and the transitions between them.
* The dialog core system which takes the dialog specification to generate questions from the user. The answers are then used to transition to the next state.
* A few custom dialog actions (java code) for a few specific steps in the dialog, the most interesting one being {{{Example.java}}} which finds 2 examples that best fit the user's characteristics.

The following sections describe these in more detail.

=== Dialog Core System
The dialog core system is built on the [https://tracinsy.ewi.tudelft.nl/pubtrac/Utilities/wiki/dialogmanager dialog manager system]. This is a complete separate system, you can easily attach this system to another frontend/GUI to change the user interaction as you like. Click the link for the details. This library takes a single json file containing the entire dialog description, plus possibly a number of additional actions (java code) and then can handle the entire dialog flow. 

=== dialog specification
As mentioned, the core controls the entire dialog from the [source:PerfectFit/Dialog/src/main/resources/dialog.json single dialog.json] file.
The code is in [source:PerfectFit/Dialog Dialog]. and the artifact has the name "movingdialog".

=== Extra Actions
There are a number of additional nonstandard actions used in our dialog:
||CheckDeadline||get a response to a suggested deadline. Will be either a confirmation message or error message.||
||DateString||convert given time (epoch = time since 1970 in seconds) to human readable string.||
||StringLength||get length of a param containing a string||
||Example||fetches the intro and goalhow text from the database and stores   it in given fields. Also stores current time. This function assumes that the   10 parameters godin_activity ..... household_size have all been been set   properly to their non-normalized values.||
||Time||get current time in seconds (since 1970)||
||TimeDifference||get difference between two timestamps (in seconds since 1970).||

The parameters are only used to select two examples. The custom update function [source:Dialog/src/main/java/tudelft/mentalhealth/perfectfit/updatefuncs/Example.java Example.java] does this, by picking the best and second-best match between the parameter settings and the settings of the 66 available examples in [source:PerfectFit/Dialog/src/main/resources/examples_with_user_data.csv examples_with_user_data.csv]


The entire dialog is specified in the file [source:PerfectFit/Dialog/src/main/resources/dialog.json dialog.json]. This is a json file that follows the specifications of the [https://tracinsy.ewi.tudelft.nl/pubtrac/Utilities/wiki/dialogmanager dialogmanager].


==== Example from Characteristics
The user's characteristics as descibed previously are used in the dialog to present two examples to the user.
To do this, the characteristic parameters are normalized first. 
Normalization turns every parameter into a number between 0 and 1.
Normalization is done by applying the formula V_norm_=clamp((V_raw_ - min)/(max-min)) where the following min and max are used, and clamp(v) = 0 if v<0, v if 0<=v<=1, or 1 if v>1.

||value||min||max||
||ttm_pa|| 0.0 || 4.0 ||
||sitting_weekend||0||22||
||extraversion||0||5.5||
||openness_to_experiences||0||5||
||exercise_identity||0||3.7||
||godin_activity||0||2||
||exercise_se||0||100||
||age||0||52||
||household_income||0||12||
||houshold_size||0||6||





=== Build, install
Both the chatserver and the movingdialog are maven projects. To built, do the following on the command line:
1. Switch to the movingdialog project and execute {{{mvn install}}} 
2. Switch to the chatserver project and execute {{{mvn install}}}

The maven build process will download additional software libraries from the web, so you need internet access to build the software.

After a succesfull build, there will be a single chatserver-X.Y.Z.war file inside the chatserver/target directory. This file contains everything needed to run the form and the chat.
To deploy this, the war file must be copied in a tomcat 8 (or higher) webapps directory after which the webpages are available to the world.

[https://tomcat.apache.org/ Apache Tomcat] is a standard webserver, It is assumed the reader knows how to install, configure and use it. 

When installed, there appear two webpages on your server:

1. http:<your server name>/chatserver/form.html that is the entry point for users. The application only stores the user data and state for the duration of the session. This normally will be in memory.
2. http://<your server name>/chatserver/chat.html. It must include a query string with the user characteristics.
Normally this page is not accessed directly by the user, but reached from the form.html page. Typically this url looks like this
​http://localhost:8080/chatserver/chat.html?godin_activity=2&exercise_se=60.5&exercise_identity=2.67&extraversion=4.0&ttm_pa=1&openness_to_experiences=2.00&sitting_weekend=10&age=25&household_income=13&household_size=3

As usual, any issues are logged to the catalina.out file, check the tomcat documentations for details.



== General project info
This section gives more general info about the project. 

[https://perfectfit-research.com/en/team Here is info on the project team]. 

Some previously developed  software for this project:

*    The implementation of a full virtual coach that helps people quit smoking and become more physically active: https://github.com/PerfectFit-project/virtual-coach-main.
*    A project to present (personalized) environments in VR: https://doi.org/10.5281/zenodo.6390738. This project was developed as part of the Master's thesis by Alkis Antoniades: http://resolver.tudelft.nl/uuid:4786dd32-eba2-41da-9079-f539cf62e72c.
*    A dialog with the virtual coach Mel for proposing preparatory activities for quitting smoking that build competencies for quitting smoking: https://doi.org/10.5281/zenodo.8302492
*    A dialog with the virtual coach Sam for proposing preparatory activities for quitting smoking and persuading users to do these activities: https://doi.org/10.5281/zenodo.6319356. More information on the virtual coach can be found in this accompanying paper: https://doi.org/10.1371/journal.pone.0277295.
*    A dialog with the virtual coach Steph for collaboratively setting daily step goals: https://doi.org/10.5281/zenodo.8382413.
*    A dialog with the virtual coach Jamie for collaboratively creating a physical activity plan: https://doi.org/10.5281/zenodo.10126244. This dialog was developed as part of the Master's thesis by Andrei Ştefan: http://resolver.tudelft.nl/uuid:04ab8ebc-f254-4928-9c44-b509b07ee22f.


Some more links and general project setup of the app:
* [https://play.google.com/store/apps/details?id=nl.sense.goalie2&hl=nl&gl=US NiceDay Healthcare nederland ] is used to create the app. NiceDay is made by [https://sense-health.com/ SenseHealth]. The sense-health page is not informative however; Maybe [https://nicedaynederland.nl/en/home-en/ this page] says more? They also have [https://github.com/senseobservationsystems/ this project] on github
*  Netherlands eScience Center seems to coordinate the project
* A separate Sensor Data app and Database is used to collect and push the data
* "Conversation" chatbot using [https://rasa.com/blog/dialogue-policies-rasa-2/ Rasa]. Rasa uses learning data to train a network which steers the dialog. See also https://www.youtube.com/watch?v=j90NvurJI4I&t=1s
* PaaS who hosts the PerfectFit services