# reflex-muc-2023

Study data, analysis and supplemental material for short paper "Exploring Dynamic Vibrotactile Feedback for Layer-based Interaction on Elastic Displays" published at Mensch und Computer 2023 - DOI: [10.1145/3603555.3608534](https://doi.org/10.1145/3603555.3608534)

## Content

| Directory         | Description                                                                                          |
| ----------------- | ---------------------------------------------------------------------------------------------------- |
| `code`            | jupyter notebooks for cleaning/converting data, plots, descriptive statistics                        |
| `data`            | raw study data                                                                                       |
| `data\trial_data` | generated data for the study (feedback mode, target layer, positions of data points in scatter plot) |
| `export`          | data generated by jupyter notebooks (large files / images are excluded from source control)          |
| `export\data`     | processed study  data                                                                                |
| `export\img`      | plots                                                                                                |
| `export\spss`     | data processed for easier analysis in SPSS                                                           |
| `mounting`        | CAD files for 3d printing mounts for vibro-motors                                                    |
| `spss`            | SPSS working files (incomplete)                                                                      |

## Study data

* Study data was pregenerated for 50 participants
* Generated data can be found in `data/trial_data`
* each participant is associated with a data file: `data_{ParticipantId}.json`

### Structure

  ``` JSON
  {
    "probandId": 0,                                 
    "blockData": [
      {
        "index": -4,
        "condition": "Combined Feedback",
        "trials": [
          {
            "trialIndex": 0,
            "layerIndex": 0,
            "resultNumber": 166,
            "resultIdx": 1,
            "points": {
              "points": [
                {
                  "pos": { "posX": 781.69552830154, "posY": 263.7441949885747 },
                  "layer": 3,
                  "center": { "posX": 1548, "posY": 617 },
                  "offset": {
                    "posX": 138.09552830153993,
                    "posY": 117.94419498857468
                  },
                  "category": 2,
                  "distance": 524930.662542738
                }

                ... // more points

              ],
              "borderDistance": [
                0, 177754.79355419573, 355509.58710839145, 533264.3806625872,
                711019.1742167829, 888773.9677709786, 1066528.7613251742,
                1244283.5548793701
              ],
              "histogramDistance": [0, 0, 38, 173, 182, 126, 127],
              "histogramLayer": [158, 118, 145, 160, 135, 136, 148]
            },
            "globalTrialIndex": -1
          },

          ... // more trials
        ]
      }
    ]
  }
  ```

* each block is associated with a specific feedback `condition` and consists of a number of trials
* blocks with a negative index are training blocks (excluded from analysis)
* each trial consists of a list of `points` that are used to draw the scatterplot
* each trial has an associated `index` (within the block), the `result number` and `layer` and a `global trial index` (for the participant over the whole experiment)
* each point has a screen `position`, a `layer`, in which it is displayed and a `category` that defines the color

## Study results

For each participant two files exist:

* `Pxx_2022-xx-xx.csv`: contains raw tracking data for analysis of turning points, and overall tracking quality
* `Pxx_2022-xx-xx.json` : contains results for each trial, especially:
  * Expected and reported result layers and result numbers
  * Layer configuration used in the task
  * Start of the Trial: `StartDate`
  * End of Interaction: `EndInteractionDate`
  * Time when layer result and number were reported: `CommitResultDate`
* __Remarks__:
  * Datasets starting with `P00` refer to test runs before the final study for testing/finetuning study setup and procedure

## Notebooks

* `study_convertMissingColumns`: used to reconstruct the empty columns for layer numbers in the first trials (one-time fix)
* `convert_results`:
  * merges separate results for each proband in one large result file (json and data) - do this, when new data is added, as `export/data/data_experiment.csv` is not in version control (too large)
  * computes additional columns
  * computes cleaned up interaction phase and saves times and markers to associated columns in results / data
* `study_general`: first raw extraction of results on separate data files
* `study_results`:
  * load data either from `export/data/results_experiment_cleanedDuration.csv` (cleaned-up interaction times) or from `export/data/results_experiment.csv`
  * computes statistics for duration and
  * correctness of results
* `study_turning-points`:
  * computes turning points
  * compute cleaned up interaction data by removing leading and trailing idle times
* `study_frametimes`: compute frametimes from `data_all.csv`

## update results

in case of new results added, execute the following steps in the given order:

1. add missing `;` at the end of the header in the newly added `.csv` files
2. run `convert_results.ipynb` to update the result including the computed values
3. run the follwing nb files in arbitrary order:
   * `study_results.ipynb`
   * `study_frametimes.ipynb`
   * `study_inLayerDurations.ipynb`
   * `study_border-durations.ipynb`
   * `study_turning-points.ipynb`

afterwards, the exported csv -files can be re-imported to spss to regenerate the statistics results.