Introduction

This repository contains the ROS implementation of BUM, a Bayesian User Model. It is divided in two packages:

• bum_ros contains the core engine, messages, auxiliary scripts, etc... that make up the BUM system. It can be used separately and only depends on ROS and the ProBT probability computation package.
• bum_ros_conductor contains the scripts needed for interaction with the user, namely for data gathering. It depends heavily on the conductor ROS package developed for the GrowMeUp project. However, it is completely decoupled from the bum_ros package, meaning that it can easily be replaced with another data source, or with a module that generates data from a different robot.

Publications

This work has been the target of a number of articles, some still under review. More information can be found on the following references:

1. Martins, G. S., Santos, L., & Dias, J. (2017). BUM : Bayesian User Model for Distributed Social Robots. In 26th IEEE International Symposium on Robot and Human Interactive Communication, RO-MAN. IEEE.

The bum_ros system

General Architecture

The bum_ros system is composed of three main nodes:

• bum_ros_node: the main node of the system, it is responsible for all of the mathematical sub-processes of the system:
• data_manager: responsible for managing the different log files generated by the system;
• evaluator: responsible for creating the metrics and figures used for system evaluation.

These are assisted by the bum_ros_conductor, which acts as our version of a possible hardware abstraction layer for the specific robot we are using.

Logs and Configuration

The bum_ros system makes use of a number of log and configuration files, which make it possible to have a distributed system and to save datasets that can later be played back in ways that emulate several system topologies.

Global Characteristic Description

The GDC file describes the problem we're tackling. It specifies the characteristics to be estimated, the evidence that each characteristic takes, as well as the ranges for all of these variables. It also specifies which characteristics are active, so that the same GDC file can be used by several nodes with minimal changes. Lastly, it specifies how many users the system is expected to encounter.

An example of a GDC file can be found in the config folder.

Evidence Log

The evidence log is generated by the data_manager. It monitors the tuple and evidence messages that circulate in the ROS system, and saves all evidences "hard" tuples that are sent by other nodes.

For example, while interacting, the conductor will publish all evidence it gathers, including tuples containing hard evidence. These are all saved by the data_manager into the evidence log file.

An example where the system would first log a hard evidence message and then a simple message evidence would look like this:

- C:
    C1: 2
  Evidence:
  	E1: 3
    E2: 2
  Identity: 1
- Evidence:
    E0: 6
    E1: 3
    E2: 2
  Identity: 3

First, the system has logged hard evidence relating some evidence to some output. Then, in the second element of the list, simple evidence (with no "C" key in the dictionary) was logged.

Execution Log

The execution log is also generated by the data_manager. This log is generated from the "soft" tuple messages published by the system, which are the output of the system's execution. This log can then be used by the evaluator node to evaluate the general performance of the BUM system, outputting our metrics and plots.

An example would look like this:

- C:
    C3: 9
  Entropy: 0.5002880096435547
  Evidence:
  - 3
  Identity: 1
- C:
    C2: 1
  Entropy: 0.12761709094047546
  Evidence:
  - 1
  - 2
  Identity: 1

Note that evidences are not saved in a dictionary. Since the characteristic's names are used for indexing the dictionary, the corresponding evidence vector can then easily be gotten from the GCD.

Ground-Truth Log

This log file keeps a dictionary for each characteristic, mapping the user's identity and relevant evidence with the output characteristic. For instance, if only identity is used:

- C1:
    1: 2
    2: 1
    3: 4
- C2:
    1: 5
    2: 3
    3: 2

This log file must be built by hand when data is gathered.

Testing the System

Without ROS

Basic testing does not require ROS at all, in fact you can just cd into the bum_ros/scripts folder and run

source prep_pypl_env.sh

python3 user_model_tests.py

to run the basic tests.

The ProBT probabilistic computation package must be installed or manually added to the PYTHONPATH via a script similar to prep_pypl_env.sh.

With ROS

Parameters

The bum_ros system depends on four parameters, indicating the filenames where all the logs, GCD and input data are saved:

• bum_ros/gcd_file: The path to the GCD file.

• bum_ros/ev_log_file: The path to the evidence log that will be saved from this run, or that will be played back (data_manager only). If this path is a directory, and the mode of operation is playback, the data_manager will play back all log files in the directory.

• bum_ros/exec_log_file: The path to the execution log that will be saved from this run (data_manager only).

• bum_ros/gt_log_file: The path to the ground truth log that will be used for evaluation (evaluator only).

• bum_ros/operation_mode: Can be either playback, listen or dual, and defines the behaviour of the data_manager, namely its processing of the evidence log file/directory. In dual mode, the system plays back evidence and records the execution of the system.

These parameters can be set by running, for example:

rosparam set /bum_ros/gcd_file "/home/vsantos/catkin_ws/src/bum_ros/bum_ros/config/data_gathering.gcd"

Launch files are provided that can serve as examples for the definition of these parameters.

Simulation

For testing with ROS, the basic system can be started by running

rosrun bum_ros bum_ros_node.py

rosrun bum_ros data_manager.py

rosrun bum_ros evaluator.py

This starts the main nodes with the default GCD, and the system is ready to receive input.

With interaction

Once the main nodes are running, running with interaction on the GrowMeUp system is a matter of running

rosrun bum_ros_conductor bum_conductor.py

this starts the interaction node, and the GrowMu robot should start speaking.

Data Gathering

For performing a data gathering run, you have to start the data manager:

rosrun bum_ros data_manager.py

as well as the conductor:

rosrun bum_ros_conductor bum_conductor.py

Naturally, you'll also need to start up any necessary drivers for the robot you are using prior to starting the system.

Testing different topologies

TODO

Useful commands

Useful command to publish evidence:

rostopic pub /bum/evidence bum_ros/Evidence "{values:[2,3,2], evidence_ids:['E1', 'E2', 'E3'], user_id: 1}"

Useful command to publish a tuple:

rostopic pub /bum/tuple bum_ros/Tuple "{char_id: 'C1', characteristic: 4, evidence: [2, 3, 2], user_id: 1, h: 0.8, hard: False}"