## LLMCMSS.08 - LRF functional specification

This is section 8 of the LLM CMS specification. It covers the area of how reporting and user feedback shall be handled and presented.

Reporting and Feedback are performed by the LRF (LLM Reporting and Feedback) component in the LLM system.

### LLMCMSS.08.00 - Document Control

Item | Value
--- | ---
LLMCMSS.08 document properties
document | LLMCMSS.08
Issue | 0.3
History - 0.1 | Created due to RefArch 0.3
History - 0.2 | added document control
History - 0.3 | - added sample alogrithms (LLMCMSS.08.03) - added LLMCMSS.08.02.15 (serve LLM-DB tree view as web pages) - added LLMCMSS.08.02.16 (static content area for web server in file system)

### LLMCMSS.08.01 LRF Motivation and driving factors

This subsection does not contain requirements, all requirements that are derviced from the deliberations in this subsection are explicitely stated in the following subsections.

There are a number of factors influencing the way reporting shall be done and the software providing this information shall be structured:

1. Training components (PTC, CTC) deliver isolated, non-weighted and un-interpreted data points and samples collected during single or multiple training exercises and sessions.
2. There are different types of consumers for the information to be distilled from all this training data:
   1. The users (seniors) doing the training themselves
   2. The trainers and coaches
   3. The medical responsible personnel
   4. The relatives of the users
3. All consumers need different compilations of the information
4. Information needs to be weighted and compared against different benchmarks and thresholds:
   1. Absolute Values
   2. Relative to peer / reference group
   3. relative to own history
   4. in the context of medical status
   5. in environmental context
      1. weather
      2. living environment
   6. synchronized with other flows of events:
      1. medication
      2. personal events
      3. time of day/year/season
5. The way this performance information has to be presented optimally also may vary due to several factors:
   1. type of senior personality
   2. psychological stability
6. The nature and format of presentation and also the information extraction algorithms may vary also amongst installation sites and employed training equipment
7. All above parameters will most probably also vary at least during the course of the trial phase
8. There may be the need for testing the reception of various forms of performance feedback and collecting this type of "meta-feedback" information (feedback about the type of feedback)
9. As a matter of system and software stability as well as a consequence of the above factors plus the fact that not all (if any at all!) types of feedback presentation and algorithms will be known at the first deployment of the LLM system, there needs to be a high flexibility and modularity in the împlementation and configuration of the preparation and presentation of training feedback information
10. For Version 1.0 of the LLM system the following limitations in the feedback generations may apply:
    1. It is assumed that the training components already deliver weighted and interpreted results (good/fair/bad, etc.). So the LRF only has to do presentation, no decision-making.
    2. No correlation across the results of different training components and/or ILC. Also, no correlation with external data.

### LLMCMSS.08.02 LRF Functional parameters

These requirements are partly derived from the factors found in LLMCMS.08.01, partly from LLMTOS, partly from other sections or external documents.

1. There shall be a reporting and feedback mechanism built as an autonomous component in the LLM system. This component shall be called LRF for brevity in the context of this specification
2. LRF shall work on measurement data deposited in the LLM-DB by training components and other sensors (Also ILC, as an example, shall be able to produce and deposit measurements data, for instance physical mobility detected by movement sensors)
3. There shall be 2 types of information calculated in the LRF, Reports and Feedback. The difference between Reports and Feedback shall not be technical, but rather conceptual and possibly in the selection of presentation methods:
   1. Reports:
      This shall be calculated values, statistics, charts, etc ...
      There may be more detailed information in a report and it may usually be shown in a RUI / Web Browser Environment
   2. Feedback:
      This shall be personalized information for the target audience
      This type of information will most of the time be presented on a local terminal in a LUI environment
4. Each generated information entity shall be qualified with the intended target audience and privacy, plus possibly additional qualification tags, plus security control.
5. Input data shall be taken from the LLM-DB
6. Generated information shall be stored in the LLM-DB, into the same structure as the inpout is taken from in order to generate feedback and/or reports based on provious feedback/reports. Alternatively the LRF shall be configurable in the way from where to take the input data and to where to put the results.
7. Generation of information shall be able to be triggered by external events from other LLMSYS components and by internal schedules
8. Completion of information generation shall be able to generate events to trigger other activity like:
   1. user interface presentation and subsequent information processing. The generated trigger event shall be able to carry properties passed on from the event triggering the information generation. These properties shall include local terminal ID, session ID and all properties to bring the report data into foreground on the respective local terminal.
   2. Workflow event(s). For this purpose the triggering event shall be able to carry flow, step, event, session and user information necessary to identify the intended action in the workflow to be triggered by feedback generation.
9. There shall be "pluggable" statistics and report generation algorithms. The Algorithm as the "loadable entity" shall be embedded in a JAVA class library that is dynamically found and loaded either at web application startup or, if allowed by the JEE application container, on demand when required the first time.
10. Selection of applicable generation algorithm shall be able to be based on any data item available in the LLM-DB
11. There shall be multiple LRF-instances per LLM-System instance, each with their own configuration and loaded algorithm sets
12. Reporting results stored in LLM-DB shall be any combination of:
    1. Graphic Images: charts, traffic-light indicators, bar-graphs, ...
    2. single text or numerical values
    3. lists and tables
    4. general HTML
13. In order to leverage already existing developments and their evolution, existing processing libraries and components shall be employed, like:
    1. GNUplot, JFreeCharts, etc .. in the presentation level
    2. decision support frameworks and rules languages for the knowledge bases
14. All configurability shall be deposited also in the LLM-DB using configuration tables and properties
15. The LLF can display an arbitrary HTML document in any LUI on any local terminal with the only restriction, that a regular URL must be provided to access the document. In order to let report results be stored at any logically sensible place, any item in the LLM-DB shall be accessable with a unique URL. This shall be handled by the LRF web-service using the unified tree API defined in LLMCMSS.04.02.14 by appending the tree path to the property containing the HTML to an URL served by the LRF service component.
16. Additionally there shall be a filesystem tree on the platform where LRF is deployed to store HTML, picture files and assistive files to be served by the RUI-webserver as static content.
    This directory tree will be used by report algorithms to deposit automatically generated picture images like charts, icons etc.
    The root of this tree shall be stored in the configuration area of the LLM-DB in 2 forms:
    1. the filesystem path on the OS platform
    2. the URL-path where the web server will serve it

### LLMCMSS.08.03 Report and Feedback Algorithm Examples

This subsection provides a number of report and feedback algorithm examples in orer to show how such an algorithm shall be constructed and to give a hint about what it shall be capable of.

#### LLMCMSS.08.03.01 - Sample Report 01 - single training session feedback

Input parameters:

- Training session result ID (to directly access the result of the respective training session in the LLM-DB tree)
- LLF-instance ID (a pointer into the LLM-DB to the device control structure of the local terminal LUI session where the result shall be displayed)

Algorithm result:

- Result shall be an HTML document like the example in LLMCMSS.06.04.07 showing:
  - A symbol for the training type performed
  - a 3-state traffic light showing RED, YELLOW, GREEN depending on the improvement level of the senior in this session
  - a short text also reflecting the improvement level

Algorithm implementation:

- take the training result from the LLM-DB with the tree API (LLMCMSS.04.02.14)
- take the user's last result in this training type from the user property "LAST_TRAINING_RESULT_<training-type>"
- compare the values to detect if user has improved
- use link to RED light picture if dis-improved, YELLOW, if constant and GREEN if user has improved, choose text accordingly
- deposit the resultant HTML document in the static content file area (LLMCMSS.08.02.16)
- send the URL of the result in a "Feedback_Ready" event to the LLF-instance passed at the input

#### LLMCMSS.08.03.02 - Sample Report 02 - Therapist overview for 1 month and 1 senior and 1 training type

Input parameters:

- month and year for which to report
- senior ID for whom to report
- training type ID for which to report
- LLM-DB tree path to the property in which the HTTP-URL of the result shall be deposited

Algorithm Result:

- bar chart with one column for eachavailable result, auto-scaled in X- and Y-axis

Implementation:

- use LLM-DB tree API (LLMCMSS.04.02.14) to select all training results for the given senior and training type
- use JFreeCharts (or similar) library to create a PNG graphics document and store it in static web file space (see LLMCMSS.08.02.16)