Changes between Initial Version and Version 1 of PerfectFit

Timestamp:

01/22/24 14:16:42 (13 months ago)

Author:

Wouter Pasman

Comment:

--

PerfectFit

@@ +1 @@
+= PerfectFit
+
+PerfectFit is a project under Willem Paul Brinkman and Nele Albers. This project is about treating smoking addiction. The application available here is about motivating people to increase their physical activity by leading them through a dialog to set a daily running or walking target.
+
+== 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].. 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. 
+
+PerfectFit Project partners are: 
+
+||Name||University||task||
+||WillemPaul||Delft|| manager||
+||Wouter||TUDelft||dialog rasa translation||
+||Walter ||escience center||manager <w.baccinelli@esciencecenter.nl>||
+||Nele Albers||TUDelft||manager?||
+||Alkis||TUDelft||VR app, chatbot with AI||
+||Milon van Vliet m.h.m.van_vliet@lumc.nl||LUMC (Leiden)||psychology, what causes cravings||
+||Milan Vliet||LUMC||Dialog writing. ||
+||Kristel Penitornas||Leiden||PhD Leiden Psychologie - dialog writing - the smoking dialog||
+||Tess||LUMC||Social Health research assistent - dialog writing||
+||Robin Richardson||Escience center|| ||
+||Bendik ||TUDelft||student 3 months now on perfectfit||
+||Bouke Scheltinga||UTwente||activity profiles, sensor data eg stappenteller,create & analyse users||
+
+
+
+There are several software systems built for this project
+* A stand-alone system with VR [wiki:CravingCues].
+* An app with virtual coach [https://github.com/PerfectFit-project/virtual-coach-main VirtualCoach] with a [https://github.com/PerfectFit-project/virtual-coach-issues/projects/15 ticket system]
+
+
+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.nsfwyoutube.com/watch?v=j90NvurJI4I&t=1s
+* PaaS who hosts the PerfectFit services
+