7. Using the web site

7.1. General navigation

First, log in to CamCOPS via a web browser.

camcops Any time you see the CamCOPS logo (it’s at the top of most pages), you can click it to get back to the main menu.

You can also log out or return to the main menu using the navigation menu at the top of the page.

7.2. Main menu

The main menu contains the following items. You may see only a subset, depending on your permissions.

7.2.1. Task, trackers, and clinical text views

Client devices upload tasks. You can view these individually in a variety of formats. You can also view numeric information over time for a patient in a tracker, and clinically relevant textual information for a patient in a clinical text view.

7.2.1.1. Filter tasks

You can configure your CamCOPS session to filter tasks according to who, what, when, and administrative criteria. By default, no task filters are set.

Under who, you can specify an optional patient forename, surname, date of birth, sex, or any form of ID number in use on your server.

Under what, you can restrict to any subset of task types, and if you wish you can restrict to completed tasks. You can also specify text contents. For example, type in “paracetamol” to find clerkings that mention paracetamol anywhere.

Under when, you can specify start and/or end dates, to find tasks in that date range.

Under administrative criteria, you can restrict to specific uploading devices or users, or the group to which a task belongs.

As well as a set filters button, there is a clear button to clear all current filters.

7.2.1.2. View tasks

This page shows all tasks meeting your current filter criteria. There are links allowing you to filter the tasks.

Each task has hyperlinks to an HTML and a PDF version. Sometimes tasks are colour-coded (there’s a key at the bottom of the page).

The HTML task view is fastest and has additional viewing options. However, you should not print the HTML view in a clinical environment, because it won’t have patient identifiers on each page. Use the PDF for that instead, or if you want to save the task as a single human-readable file.

When you view a task in HTML mode, there are some additional hyperlinks at the bottom:

  • Task help. Shows you general information about the task.

  • Task details. Shows you information about the task’s data structure.

  • View raw data: XML | FHIR. This shows you the raw structure as XML, or JSON-formatted FHIR format, including stored data and calculated fields such as summary scores.

    All fields have an associated comment, and these comments are displayed in the XML. You can also view these comments, and other helpful details about the data structure of every task, in the task details – see Task list.

  • View anonymised version: HTML | PDF. This shows you a version with patient identification details hidden. It is not guaranteed to be free of identifying material, though; for example, it makes no effort to remove patient details from free text 4.

  • Administrators have additional options; see administrative options.

  • View PDF. A link to the PDF version.

PDF versions include patient identifiers on each page, to meet normal UK clinical standards, and if the task involved recording a clinician’s views or assessments, the PDF will include a template signature box for on-paper authentication by the clinician.

Specimen tasks in PDF format:

7.2.1.3. Trackers for numerical information

Many tasks produce numerical information, like total scores. Trackers allow you to view numerical information from these tasks, or a subset of them, over time. The resulting graphs are time-aligned within the tracker, across all tasks (i.e. all graphs have the same time axis).

Not all tasks offer trackers.

Some tasks offer more than one numerical value, and therefore provide more than one graph.

To configure a tracker, choose a patient by an ID number. You can, optionally, specify a start and/or end date, and you can restrict to specific tasks.

You can view trackers in HTML or PDF mode, or view the data used to generate them in XML format.

Specimen tracker:

Warning

Both trackers and CTVs collate information from multiple tasks. They therefore perform a consistency check to ensure that patient ID information is the same across all tasks. (Did someone mis-spell a name, for example – or worse, mis-file information by entering the wrong ID number?) Beware if the consistency check fails; you will need to ensure manually that all the data relates to the same patient.

7.2.1.4. Clinical text views

Like a tracker, a clinical text view (CTV) collects information across many tasks for one patient. Like a tracker, a CTV is configured for a patient, and can be configured for a date range and/or a subset of tasks. Like a tracker (and like a book), a CTV flows from older to newer information. Unlike a tracker, a CTV produces text for each task, not numbers. The text is intended to be clinically useful. For example, simple questionnaires produce their summary information. The ACE-III produces its total but also its subscale scores. Clinical clerkings produce their full text. All tasks appear in the CTV, but some tasks simply indicate that they have been performed.

You can view CTVs in HTML or PDF mode, or view the data used to generate them in XML format.

In the HTML view of a CTV, all tasks provide hyperlinks to the full representation of each task, so you can delve into more detail for any task of interest.

Specimen CTV:

Warning

Both trackers and CTVs collate information from multiple tasks. They therefore perform a consistency check to ensure that patient ID information is the same across all tasks. (Did someone mis-spell a name, for example – or worse, mis-file information by entering the wrong ID number?) Beware if the consistency check fails; you will need to ensure manually that all the data relates to the same patient.

7.2.2. Patients

7.2.2.1. Manage patients and their task schedules

You can schedule tasks for a patient to complete on their own tablet with the CamCOPS app running in Single User Mode.

OVERVIEW

The key pieces of information your patient needs to know are:

  • Where they can download CamCOPS for their tablet, phone, laptop etc (Google Play, Apple Store, GitHub)

  • The location of the CamCOPS server

  • Their unique access key

How you choose to communicate these to your patients is up to you. CamCOPS supports a simple email workflow.

Your task schedules and patients will be associated with a group that you administer. You must set the intellectual property (IP) settings for this group to describe the contexts in which your group operates (clinical, commercial, etc.). Any tasks you schedule for a patient need to be permitted for these contexts.

  • First, create a task schedule for your study (Manage task schedules ‣ Add a task schedule). Here you can specify the From, CC and BCC fields for your emails, along with an email template. The template can be customised to include the location of the server, the patient’s name, their unique access key, and a unique URL that patients can use the first time they launch the app. This last option will register their patient automatically with the server, without the need to enter the server and access key (Android and iOS only).

  • Next add items to your schedule (Edit items from the table of schedules):

    • Select the task from the drop-down

    • Enter the time from the start of the schedule when the patient may begin the task and the time the patient has to complete the task. These times can be expressed as a combination of months, weeks and days (defined here as 1 month = 30 days, 1 week = 7 days).

From the Patient Task Schedules page you can add a new patient. The patient must have enough identifiable information to match the uploading and finalizing ID policies of the group. Here you can also assign one or more task schedules to the patient. You can specify the start date of the schedule or leave it blank. If you leave it blank, the start date will be the date the patient first downloads the schedule from the server. You can assign the same schedule multiple times to a patient, though you should only do this once the patient has completed the tasks for all previous instances of the same schedule.

Note

Advanced use: There is an optional form field to specify any patient-specific settings for the tasks. This is a JSON object keyed on the task table name, e.g.:

{
    "task1": {
        "name1": "value1",
        "name2": "value2"
    },
    "task2": {
        "name1": "value1"
    }
}

Refer to the relevant task documentation for any settings that can be applied in this way.

If the patient has been successfully created, they should now appear in the table along with the unique access key that they need for registration. The address of the server is also displayed on this page for convenience. If you have provided an email address for the patient and a “from” address for the task schedule, Send email… will open a form with the email body populated from the template associated with the schedule.

You can view a patient’s progress through the schedule by following the link to the named schedule from the table. From this table you can view the uploaded task responses as HTML or PDF. Anonymous tasks will be listed in this table but you will not see the responses. Here you can also view a list of emails sent to the patient and view their details.

Note

If you edit patient details after the patient has registered, the client will pick up the changes when it next picks up schedule updates.

If you change the patient’s ID numbers, though, the patient may have to redo tasks (completed tasks are sought by any current ID number).

INTERFACE

Patients and their task schedules

This page manages patients and their associated schedules. It offers:

  • CamCOPS server location

    • Shows the URL for this server’s API – the URL that client devices should use to communicate with the CamCOPS server.

  • Patients (and their task schedules). For every patient set up for scheduling, this shows:

    • Their basic details (name, etc.);

    • identification numbers associated with them;

    • their access key;

    • task schedules assigned to them (hyperlinked to show their progress on this schedule), along with a button to e-mail them (using that schedule’s template), if authorized;

    • a link to edit the patient or assign schedules to them;

    • a link to delete the patient.

  • A link to add a patient.

  • A link to manage task schedules, if authorized.

View a patient’s progress on a schedule

This page shows:

  • Scheduled tasks for this patient on this schedule (including task type, “due from” date, “due by” date, whether the task has been created/uploaded to the server, and whether it is complete or incomplete).

    • If the task is due now and is not complete, a due symbol will be displayed.

    • If the task is present on the server, you will be able to view it as HTML or PDF (see View tasks).

    • If the task is anonymous, some of this information will be unknown. CamCOPS treats anonymity seriously.

  • Emails previously sent to the patient about this schedule. You can view them, if authorized.

  • A link to e-mail the patient (using that schedule’s template).

  • A link back to manage patients and their tasks.

Task schedules

This page manages task schedules themselves. It offers:

  • Task schedules. For every schedule configured, this shows:

    • the associated group;

    • the schedule’s name;

    • links to edit and delete the schedule;

    • the schedule’s items and a link to edit items.

  • A link to add a task schedule.

  • A link back to manage patients and their tasks.

Task schedule items (for a specific schedule)

This page allows you to view and edit items for a specific schedule. It offers:

  • For every item associated with this schedule,

    • the task;

    • when the task is due from (relative to the start of the schedule);

    • how long the task is due within (once it falls due);

    • links to edit and delete the item.

  • A link to add a task schedule item.

  • A link back to manage task schedules.

7.2.3. Research views

7.2.3.1. Basic research dump (fields and summaries)

This option allows you to download a spreadsheet or similar file that contains one worksheet for every type of task for which “current” data is present 1 (one row per task instance), and includes raw data and summary measures (e.g. total scores).

You can choose to dump everything that you have permission for, or restrict to the criteria you’ve set in your current session filter, or specify tasks and/or groups manually.

Formats

The download formats include:

  • An R script, which encapsulates the data and creates R objects for you. You can pull in the data from another script (or the command line) via th source command. It uses data.table.

  • OpenOffice/LibreOffice spreadsheet (ODS) format.

  • XLSX (Microsoft Excel).

  • A ZIP file, containing multiple TSV files, one per worksheet. This is the least human-friendly format, but is OK for automatically importing into statistics packages.

    • For TSV, NULL values are represented by blank fields and are therefore indistinguishable from blank strings. The Excel dialect of TSV is used. If you want to read TSV files into R, try:

      mydf = read.table("something.tsv", sep="\t", header=TRUE, na.strings="", comment.char="")

      Note that R will prepend ‘X’ to variable names starting with an underscore; see ?make.names. Inspect the results with e.g. colnames(mydf) or View(mydf). However, if you simply want to import into R, CamCOPS will provide you an R script directly, which may be simpler.

There are also advanced data dumps in other formats (see below).

Delivery method

  • Serve immediately.

    Depending on your administrator’s preference, you may be permitted to download data with a single click. (“Immediate” downloads tie up part of the “front end” web server for a while as it builds the data file, which may be large, so it’s often preferable to permit just e-mail and queued download options, as below.)

  • E-mail.

    You can also choose to have the dump emailed to you, providing your user is set up with a valid email address. This is useful for large exports that may be time consuming.

  • Queued download.

    You can ask the server to build a file for you. It will e-mail you when it’s ready (assuming your e-mail address is configured) and you can then collect it from the Download area.

    Your administrator will set a time limit and a capacity limit for your download area. Files that get too old will be deleted, and you will not be allowed to create files that would exceed your capacity limit.

7.2.3.2. Advanced research dump (SQL or database)

This more sophisticated research dump generates a fully structured SQLite binary database of the data you select (or, if you prefer, the SQL text to create it). By default, BLOBs (binary large objects) are skipped, because they can be very large, but you can choose to include them.

You can select the information you want, exactly as for the basic research dump.

Some user information will be provided (e.g. user names), but security information (e.g. passwords) is removed prior to the download.

As for the basic research dump, summary information is added to tables as they are created. For example: the internal PHQ9 table contains scores for individual questions, but not the total (which is calculated dynamically). When you download the data, the total (amongst other things) is calculated and added to the data that you download (within the SQLite table or CSV file).

The delivery methods are as before.

7.2.3.3. Download area

This is where you can pick up data files that you have queued for downloading (see above).

7.2.3.4. Task list

This provides information on all tasks in CamCOPS. For each task, you can view:

  • Task code (internal table name) and details, including:

    • Table definitions (data stored by CamCOPS in its database).

    • Summary elements (summary measures calculated by CamCOPS dynamically).

    • Tracker elements (see trackers above).

    • FHIR structure.

  • The task’s short name.

  • The task’s long name, hyperlinked to its online help.

Note

What do we mean by “summary” information?

For example, the PHQ-9 tasks stores the answers for 9 symptom questions in fields q1 to q9, and one overall impact answer in the q10 field. It also stores information to link the record to the patient in question, and some administrative information (relating to record history, editing time, etc.)

However, it doesn’t store summary information on the server 5; rather, summary measures are calculated on demand. For this task, summary measures include:

  • is_complete (Boolean): is the task complete (no missing values)?

  • total (integer): total score

  • n_core (integer): number of core depressive symptoms reaching threshold

  • n_other (integer): number of other depressive symptoms reaching threshold

  • n_total (integer): total number of symptoms reaching threshold

  • is_mds (Boolean): does this patient meet the PHQ9 criteria for major depressive syndrome?

  • is_ods (Boolean): does this patient meet the PHQ9 criteria for other depressive syndrome?

  • severity (text): textual description of depressive severity by the standard PHQ9 scoring method.

7.2.3.5. Inspect table definitions

This option allows you to view the database structure of the CamCOPS server database, as data definition language (DDL), meaning the subset of SQL used to create tables. In SQL dialects that support it (e.g. MySQL), the DDL contains comments for every field, usually in considerable detail, so viewing the DDL this is a good way of understanding how CamCOPS tasks store their data. However, the task information in the task list may be simpler!

7.2.4. Reports

7.2.4.1. Run reports

CamCOPS has a set of build-in reports; for example, to count tasks, or list client devices, or find patients by diagnostic inclusion/exclusion criteria. You can explore and run these from the Reports menu.

Reports are used in two stages: (1) configure, (2) run.

The configuration stage provides an interface to select options for the report. This includes the output format (e.g. HTML, TSV), but may include more (e.g. for reports that find patient by diagnosis). Once you’ve chosen the options, click “View Report”. Behind the scenes, what the configuration stage actually does is generate a URL for the final report.

Output formats include:

  • HTML, for online use. This is typically paginated, may show configuration parameters, and sometimes shows the SQL used to generate the report. (To view SQL in a formatted state, paste it into an online SQL formatter 3.) When you view the report in HTML format, you will see that the browser’s URL contains your report configuration information. This means that you can save this report for later.

  • ODS: OpenOffice spreadsheet format.

  • TSV: tab-separated values (TSV) format.

  • XLSX: Microsoft Excel.

An example of keeping the URL for later: suppose you regularly want to find patients between the ages of 20 to 65 inclusive, with an ICD-9-CM inclusion diagnosis of depression (e.g. 311) 2, excluding bipolar affective disorder (e.g. anything starting 296) or eating disorders (e.g. 307.1). You could create a report with these age restrictions and inclusion and exclusion diagnoses, and view it. The URL would look like this:

https://my.camcops.site/report?diagnoses_inclusion=311%25&age_maximum=65&which_idnum=1&rows_per_page=&viewtype=html&diagnoses_exclusion=296%25&diagnoses_exclusion=307.1%25&age_minimum=20&report_id=diagnoses_finder_icd9cm&page=1

If you copy this URL, you can run the report again without having to configure it manually. Here’s an approximate ICD-10 equivalent (same age range; include F32% and F33%; exclude F30%, F31%, F50%):

https://my.camcops.site/report?diagnoses_inclusion=F32%25&diagnoses_inclusion=F33%25&age_maximum=65&which_idnum=1&rows_per_page=&viewtype=html&diagnoses_exclusion=F30%25&diagnoses_exclusion=F31%25&diagnoses_exclusion=F50%25&age_minimum=20&report_id=diagnoses_finder_icd10&page=1

7.2.5. Group administrator options

See group administrator options in the Administrator’s Guide.

7.2.6. Superuser options

See superuser options in the Administrator’s Guide.

7.2.7. Settings

7.2.7.1. Choose group into which to upload data

CamCOPS has a concept of “groups” (e.g. a clinical group or a research study). When one of your tablets or other client devices (i.e. a client device using your username) uploads data to this CamCOPS server, it will store its patient and task details in a group. Which group should this be? You get to choose here, from the groups that you are a member of (and have permission to upload into).

7.2.7.2. View your user settings

Show information about your user, including:

  • username

  • e-mail address

  • language

  • group memberships (with associated permissions)

7.2.7.3. View server information

Show information about the server, including:

  • patient identification number systems

  • recent activity

  • tasks available

7.2.7.4. Change password

Use this option to change your password.

7.2.7.5. Multi-factor authentication settings

Choose your preferred multi-factor authentication (MFA) method. When this is enabled, users are required to enter a six-digit code in addition to their username and password. Your server administrator may have enabled a subset of these, so some may be unavailable. The full set of options is:

  • Use an app such as Google Authenticator or Twilio Authy.

  • Send a code by e-mail.

  • Send a code by SMS text message. SMS requires the server administrator to set up a paid account with a supported provider (currently Kapow or Twilio SMS).

  • Disable multi-factor authentication. (This is less secure!)

Administrators can enforce MFA by omitting none from the list of supported MFA methods on the server. See MFA_METHODS. If they do so, a user without MFA will be prompted to set it up once they have logged in.

7.2.8. Help

7.2.8.1. CamCOPS documentation

Click “CamCOPS documentation” for this manual.

Footnotes

1

“Current” means that this download will skip historical versions of tasks that have been edited, and just provide the latest version.

2

ICD-9-CM diagnostic codes: https://en.wikipedia.org/wiki/List_of_ICD-9_codes_290%E2%80%93319:_mental_disorders

3

e.g. https://sqlformat.org/; https://www.freeformatter.com/sql-formatter.html

4

For a software product that takes de-identification seriously, see e.g. CRATE, described in Cardinal RN (2017), https://doi.org/10.1186/s12911-017-0437-1, and available from https://crateanon.readthedocs.io/.

5

https://en.wikipedia.org/wiki/Database_normalization