@bdelab/roar-firekit/README.md

A library to facilitate Firebase authentication and Cloud Firestore interaction for ROAR apps

[![npm version](https://badge.fury.io/js/@bdelab%2Froar-firekit.svg)](https://badge.fury.io/js/@bdelab%2Froar-firekit)
![NPM License](https://img.shields.io/npm/l/@bdelab/roar-firekit)

# roar-firekit

Welcome to roar-firekit! Roar-firekit helps you store the data from your [ROAR application](https://dyslexia.stanford.edu/roar/) in [Cloud Firestore](https://cloud.google.com/firestore).

## Installation

You can install [roar-firekit from npm](https://www.npmjs.com/package/@bdelab/roar-firekit) with

```bash
npm i @bdelab/roar-firekit
```

## Usage

Roar-firekit is agnostic about where your data comes from, but I anticipate most users will use roar-firekit with their experiments written in [jsPsych](https://www.jspsych.org/).

The main entrypoint to roar-firekit's API is the [[`RoarAppkit`]] class.  Its
constructor expects an object with keys `userInfo`, `taskInfo`, and `config`, where
`userInfo` is a [[`UserDataInAdminDb`]] object, `taskInfo` is a
[[`TaskVariantInput`]] object, and `config` is a [[`AssessmentConfigData`]] object.

### Constructor inputs

#### `userInfo`

User information is encapsulated in a [[`UserDataInAdminDb`]] object. Its only required
key is `id`, which should be the current user's ROAR UID, which is also sometimes called the ROAR PID:

```javascript
const minimalUserInfo = { id: 'roar-user-id' };
```

But you can supply other information about the user if you know it:

```javascript
const fullUserInfo = {
  id: 'roar-user-id',
  birthMonth: 7,
  birthYear: 2014,
  classId: 'roar-class-id',
  schoolId: 'roar-school-id',
  districtId: 'roar-district-id',
  groupId: 'roar-group-id',
  userCategory: 'student',
}
```

#### `taskInfo`

Information about the current task is encapsulated in a [[`TaskVariantInput`]] object. Here is the task information for a fictitious "Not Hotdog" task:

```javascript
const taskInfo = {
  taskId: 'nhd',
  taskName: 'Not Hotdog',
  variantName: 'Not Hotdog, one block',
  taskDescription: 'A demonstration task using the hot dog / not hot dog problem',
  variantDescription: 'One block, random order',
  blocks: [
    {
      blockNumber: 1,
      trialMethod: "random-without-replacement",
      corpus: "pointer-to-location-of-stimulus-corpus",
    },
  ]
}
```

#### `config`

The config object contains configuration information for your Firebase project. You may want to store your config object in separate javascript file (named "roarConfig.js" for this documentation). A template is provided below

<details>
  <summary>Click to expand!</summary>

  ```javascript
  export const roarConfig = {
    "firebaseConfig": {
      "apiKey": "insert your firebase API key here",
      "authDomain": "insert your firebase auth domain here",
      "projectId": "insert your firebase project ID here",
      "storageBucket": "insert your firebase storage bucket here",
      "messagingSenderId": "insert your firebase messaging sender ID here",
      "appId": "insert your firebase app ID here",
      "measurementId": "insert your firebase measurement ID here",
    },
    "rootDoc": ["some collection name", "some document name"],
  }
  ```

</details>

##### `firebaseConfig`

To get the `firebaseConfig` fields, see [this article](https://support.google.com/firebase/answer/7015592#zippy=%2Cin-this-article) on how to retrieve your firebase config. TLDR: go directly to [your project's settings](https://console.firebase.google.com/project/_/settings/general/), scroll down to "SDK setup and configuration," click the "Config" radio button, and copy the snippet for your app's Firebase config object.

##### `rootDoc`

The `rootDoc` is an array of strings representing the document under which all ROAR data will be stored.  Note that `rootDoc` does not have to be in the actual root of your Cloud Firestore database.

### Constructing the firekit

With the above defined input, you would construct a firekit using

```javascript
import { RoarAppkit } from '@bdelab/roar-firekit';
import { roarConfig } from './roarConfig.js';

// Insert input definition code from above

const firekit = new RoarAppkit({
  userInfo: minimalUserInfo,
  taskInfo,
  config: roarConfig,
})
```

## Starting a run

Starting a run writes the user, task, and run information to Cloud Firestore:

```javascript
await firekit.startRun();
```

If you are using roar-firekit with jsPsych, you should call this method before
experiment starts, either by awaiting it before the `jsPsych.run` method,

```javascript
await firekit.startRun();
jsPsych.run(timeline);
```

or by calling it as part of the `on_timeline_start` callback,

```javascript
const procedure = {
  timeline: [trial1, trial2],
  on_timeline_start: function() {
    await firekit.startRun();
  }
}
```

## Writing a trial to Firestore

After starting a run, you can write individual trial data to Cloud Firestore using the `writeTrial` method.
This method can be added to individual jsPsych trials by calling it from
the `on_finish` function, like so:

```javascript
var trial = {
  type: 'image-keyboard-response',
  stimulus: 'imgA.png',
  on_finish: function(data) {
   firekit.writeTrial(data);
  }
};
```

Or you can call it from all trials in a jsPsych
timeline by calling it from the `on_data_update` callback. In this
case, you can avoid saving extraneous trials by conditionally calling
this method based on the data. For example:

```javascript
initJsPsych({
  on_data_update: function(data) {
    if (data.saveToFirestore) {
      firekit.addTrialData(data);
    }
  }
});
const timeline = [
  // A fixation trial; don't save to Firestore
  {
    type: htmlKeyboardResponse,
    stimulus: '<div style="font-size:60px;">+</div>',
    choices: "NO_KEYS",
    trial_duration: 500,
  },
  // A stimulus and response trial; save to Firestore
  {
    type: imageKeyboardResponse,
    stimulus: 'imgA.png',
    data: { saveToFirestore: true },
  }
]
```

## Finishing a run

After your experiment is over, you can mark it as completed in Firestore using the `finishRun` method. For example, you can call this method in the [`on_finish` (experiment) callback](https://www.jspsych.org/7.1/overview/events/#on_finish-experiment):

```javascript
initJsPsych({
  on_finish: function(data) {
    firekit.finishRun();
  }
});
```

## Full example

The following is an example jsPsych experiment that implements the NoHotdog assessment while writing data to Cloud Firestore using roar-firekit.

<details>
  <summary>Click to expand!</summary>

  ```javascript
  import { initJsPsych } from 'jspsych';
  import preload from '@jspsych/plugin-preload';
  import htmlKeyboardResponse from '@jspsych/plugin-html-keyboard-response';
  import imageButtonResponse from '@jspsych/plugin-image-button-response';
  import { RoarAppkit } from '@bdelab/roar-firekit';
  import { roarConfig } from "./roarConfig.js";

  const taskInfo = {
    taskId: 'nhd',
    taskName: 'Not Hotdog',
    variantName: 'nhd-1block-random',
    taskDescription: 'A ROAR demonstration using the hot dog / not hot dog task.',
    variantDescription: 'One block, random order',
    blocks: [
      {
        blockNumber: 1,
        trialMethod: 'random-without-replacement',
        corpus: 'assets',
      },
    ],
  };

  const minimalUserInfo = { id: 'roar-user-id' };

  const firekit = new RoarAppkit({
    userInfo: minimalUserInfo,
    taskInfo,
    config: roarConfig,
  });

  await firekit.startRun();

  const jsPsych = initJsPsych({
    on_data_update: function (data) {
      if (data.saveToFirestore) {
        firekit.writeTrial(data);
      }
    },
    on_finish: function () {
      firekit.finishRun();
    },
  });

  // This example assumes that the hot dog / not hot dog images are stored in the
  // assets folder.
  const numFiles = 30;
  const hotDogFiles = Array.from(Array(numFiles), (_, i) => i + 1).map(
    (idx) => new URL(`../assets/hotdog/${idx}.jpg`, import.meta.url),
  );
  const notHotDogFiles = Array.from(Array(numFiles), (_, i) => i + 1).map(
    (idx) => new URL(`../assets/nothotdog/${idx}.jpg`, import.meta.url),
  );
  const allFiles = hotDogFiles.concat(notHotDogFiles);
  const allTargets = allFiles.map((url) => {
    return { target: url, isHotDog: !url.pathname.includes('nothotdog') };
  });

  let timeline = [];

  /* preload images */
  const preloadImages = {
    type: preload,
    auto_preload: true,
  };
  timeline.push(preloadImages);

  /* define welcome message trial */
  const welcome = {
    type: htmlKeyboardResponse,
    stimulus: 'Welcome to ROAR-HD, a rapid online assessment of hot dog differentiating ability. Press any key to begin.',
  };
  timeline.push(welcome);

  const hotDogTrials = {
    timeline: [
      {
        type: htmlKeyboardResponse,
        stimulus: '<div style="font-size:60px;">+</div>',
        choices: 'NO_KEYS',
        trial_duration: 500,
      },
      {
        type: imageButtonResponse,
        stimulus: jsPsych.timelineVariable('target'),
        choices: ['Hot Dog', 'Not a Hot Dog'],
        prompt: 'Is this a hot dog?',
        data: { saveToFirestore: true },
        on_finish: function (data) {
          data.correct = jsPsych.timelineVariable('isHotDog') == data.response;
        },
      },
    ],
    timeline_variables: allTargets,
    sample: {
      type: 'without-replacement',
      size: 20,
    },
  };

  timeline.push(hotDogTrials);

  const fixation = {
    type: htmlKeyboardResponse,
    stimulus: 'You are all done. Thanks!',
    choices: 'NO_KEYS',
  };
  timeline.push(fixation);

  jsPsych.run(timeline);
  ```

</details>