Skip to content

Commit

Permalink
minor updates to study-config table
Browse files Browse the repository at this point in the history
  • Loading branch information
@casaout
casaout authored Mar 8, 2024
1 parent 2cbbcd0 commit d89ab2c
Showing 1 changed file with 20 additions and 25 deletions.
45 changes: 20 additions & 25 deletions documentation/RESEARCH.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,54 +6,49 @@ This project was created by and for researchers who want to ask study participan
# Customizing PersonalAnalytics
To customize PersonalAnalytics for your research study, please consider the following steps:

<!-- tbd: Sebastian: update -->

1. Fork the project to work in your own repository.
2. Update the `study.config.ts`-[file](../src/electron/shared/study.config.ts) with your custom study-related settings. Hereby, you can add your custom study name, study title, privacy policy, export upload url as well as contact data. In addition, you can customize which computer interaction tracker isrunning, and if you want to prompt the user to self-report on one or several questions in the experience sampling component.
2. Update the [study configuration-file](../src/electron/shared/study.config.ts) (`study.config.ts`) with your custom study-related settings (see details below). Hereby, you can add your custom study name, study title, privacy policy, export upload url as well as contact data. In addition, you can customize which computer interaction tracker isrunning, and if you want to prompt the user to self-report on one or several questions in the experience sampling component.
3. (optional) If you require further customizations, you can create them in the code (see [Contributions Guide](#contributions-guide)).
4. Use Github Actions (see [build.yml](https://github.com/HASEL-UZH/PersonalAnalytics/blob/feature/electron/.github/workflows/build.yml)) to build and deploy PersonalAnalytics and allow your participants to use it. Using the method, PersonalAnalytics can automatically update your participants' installations with new releases

## General Configuration of PersonalAnalytics (edit in `study.config.ts`)
| Parameter | Description | Change Required | Default Value |
|---------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------|---------------|
| `name` | The name of the study. This is shown in various places of PersonalAnalytics, such as the PersonalAnalytics' menu icon tooltip, the experience sampling and when exporting the study data. | ✅ | |
| `shortDescription` | A short description of the study. This is shown during the onboarding process, in the about page, and when exporting the study data. | ✅ | |
| `infoUrl` | A URL to a website that provides more information about the study. This is shown during the onboarding process, in the about page and when exporting the study data. | ✅ | |
| `privacyPolicyUrl` | A URL to a website that provides the privacy policy of the study. This is shown during the onboarding process, in the about page and when exporting the study data. | ✅ | |
| `uploadUrl` | A URL to a service where participants can upload their study data. This is shown when exporting the study data. | ✅ | |
| `contactName` | The name of the person that participants can contact. This is shown during the onboarding process, in the about page, when exporting the study data, in case of errors and in the application's menu when requesting help or reporting an issue. | ✅ | |
| `contactEmail` | An email address that participants can use to contact the study organizers. This is shown during the onboarding process, in the about page, when exporting the study data, in case of errors and in the application's menu when requesting help or reporting an issue. | ✅ | |
| `subjectIdLength` | The length of the subject ID that is generated for each participant. This is used to identify the participant's data. | | `6` |
| `dataExportEnabled` | Whether the participant should be able to export their data. If enabled, participants can export their study data through the application's menu. | | `true` |
| `name` | The name of the study. It is shown in various places of PersonalAnalytics, such as the the about page, the experience sampling and when exporting the study data. | ✅ | |
| `shortDescription` | A short description of the study. It is shown during the onboarding process, in the about page, and when exporting the study data. It should describe the study goal and summarize the collected data and how the data is analyzed. | ✅ | |
| `infoUrl` | A link to a website (starting with `https://`) to provide additional details about the study. It is shown during the onboarding process, in the about page and when exporting the study data. | ✅ | |
| `privacyPolicyUrl` | A link to a website (starting with `https://`) that describes the privacy policy of the study. It is shown during the onboarding process, in the about page and when exporting the study data. | ✅ | |
| `uploadUrl` | A link to a website (starting with `https://`) that offers file-uploads for the participants to share their study data (e.g. SharePoint, Dropbox, Dropfiles website). It is shown when exporting the study data. | ✅ | |
| `contactName` | The name of the Principal Investigator (PI) that participants can contact. It is shown during the onboarding process, in the about page, when exporting the study data, in case of errors and in the application's menu when requesting help or reporting an issue. | ✅ | |
| `contactEmail` | An email address that participants can use to contact the researchers. It is shown during the onboarding process, in the about page, when exporting the study data, in case of errors and in the application's menu when requesting help or reporting an issue. | ✅ | |
| `subjectIdLength` | The length of the subject ID that is automatically generated for each participant when PersonalAnalytics is installed (e.g. `8JE7DA`). | | `6` |
| `dataExportEnabled` | Whether the participant should be able to export their data. If enabled, participants can export their study data through the context menu. | | `true` |

### Tracker Configuration (edit `trackers` in `study.config.ts`)
#### WindowsActivityTracker
| Parameter | Description | Change Required | Default Value |
|---------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------|---------------|
| `enabled` | Whether the WindowsActivityTracker should be enabled. If enabled, the WindowsActivityTracker will collect data about the participant's application usage. | | `true` |
| `intervalInMs` | The interval in milliseconds at which the WindowsActivityTracker should collect data. | | `1000` |
| `trackUrls` | Whether the WindowsActivityTracker should track the URLs of the websites that the participant visits. On macOS: If this is enabled, participants need to enable the accessibility permission through the system settings. (They will be prompted to do so when running the application for the first time.) | | `false` |
| `trackWindowTitles` | Whether the WindowsActivityTracker should track the titles of the windows that the participant uses. On macOS: If this is enabled, participants need to enable the screen recording permission through the system settings. (They will be prompted to do so when running the application for the first time.) | | `true` |
| `enabled` | Whether the WindowsActivityTracker is enabled. If enabled, the WindowsActivityTracker will collect data about the participant's application usage, including app names, window titles, visited URLs etc. | | `true` |
| `intervalInMs` | The interval in milliseconds at which the WindowsActivityTracker should collect data. We recommend to keep the default. | | `1000` |
| `trackUrls` | Whether the WindowsActivityTracker should track the URLs of the websites that the participant visits. This feature only works on macOS. When enabled, participants need to enable the accessibility permission through the system settings, and will automatically be prompted to do so when running the application for the first time. | | `false` |
| `trackWindowTitles` | Whether the WindowsActivityTracker should track the titles of the windows that the participant uses. On macOS and when enabled, participants need to enable the screen recording permission through the system settings, and will automatically be prompted to do so when running the application for the first time. | | `true` |

#### UserInputTracker
| Parameter | Description | Change Required | Default Value |
|---------------------|------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------|---------------|
| `enabled` | Whether the UserInputTracker should be enabled. If enabled, the UserInputTracker will collect data about the participant's keyboard and mouse input. | | `true` |
| `enabled` | Whether the UserInputTracker is enabled. If enabled, the UserInputTracker will collect data about the participant's keyboard and mouse input (number of keystrokes, number of clicks, pixels moved and pixels scrolled in the defined interval). | | `true` |
| `intervalInMs` | The interval in milliseconds at which the UserInputTracker collects and stores the aggregated data. | | `10000` |

#### ExperienceSamplingTracker
| Parameter | Description | Change Required | Default Value |
|-------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------|---------------------------|
| `enabled` | Whether the ExperienceSamplingTracker should be enabled. If enabled, the ExperienceSamplingTracker will prompt the participant to self-report on one or several questions at customizable times (see configuration below). | | `true` |
| `enabled` | Whether the ExperienceSamplingTracker is enabled. If enabled, the ExperienceSamplingTracker will prompt the participant to self-report on one or several questions at customizable times (see configuration below). | | `true` |
| `intervalInMs` | The interval in milliseconds at which the ExperienceSamplingTracker should prompt the participant to self-report. | | `1000*60*60*3` (3 hours) |
| `samplingRandomization` | Wether the ExperienceSamplingTracker should include a randomization for the time at which the participant is prompted to self-report. A value between 0 and 1. If enabled (value bigger than 0), the ExperienceSamplingTracker will randomly calculate a value that is between `intervalInMs` plus/minus `intervalInMs * samplingRanomization` | | `0.1` |
| `scale` | The questions scale. This applies to all questions. | | `7` |
| `questions` | An array of questions that the participant should self-report on. Each question has a `text` and a `scale` property. The `text` property is the question that the participant should answer. The `scale` property is the scale that the participant should use to answer the question. | ✅ | |
| `responseOptions` | An array of arrays with labels for the Likert-scale question. This can be either two labels that will be displayed on the left and right (e.g., `['strongly disagree', 'strongly agree']`) or three labels (e.g., `['strongly disagree', 'neutral', 'strongly agree']`). | ✅ | |


| `samplingRandomization` | Wether the ExperienceSamplingTracker should include a randomization for the time at which the participant is prompted to self-report. A value between 0 and 1. If enabled (value bigger than 0), the ExperienceSamplingTracker will randomly calculate a value that is between `intervalInMs` plus/minus `intervalInMs * samplingRanomization`. | | `0.1` |
| `scale` | The number of items of the Likert-scale. Per the definition, it should be an odd number, ideally between 3-9. It applies to all questions. | | `7` |
| `questions` | An array of questions that the participant should self-reflect on. Each question has a `text` and a `scale` property. The `text` property is the question that the participant should answer. The `scale` property describe the labels of the scale that the participant should use to answer the question. | ✅ | |
| `responseOptions` | An array of arrays with labels for the Likert-scale question. This can be either two labels that will be displayed on the left and right (e.g., `['strongly disagree', 'strongly agree']`) or three labels (e.g., `['strongly disagree', 'neutral', 'strongly agree']`). The same order as defined for the `questions` applies. | ✅ | |

// show a checkmark or a cross

# Contributions Guide
Anyone is welcome to contribute to PersonalAnalytics by extending it with new trackers or improving existing ones.
Expand Down

0 comments on commit d89ab2c

Please sign in to comment.