Skip to content

CAIMAN User Guide

Calibration Implementation Manager (CAIMAN) is used to maintain and generate CLAS12 Calibration Dashboards. The dashboards' website is read-only; this user guide will show you how to edit the dashboards.

Getting Started

On ifarm, run: 

module load caiman
caiman

A usage guide will print out, showing the various command line options; use --help if you want to see even more.

Troubleshooting: Access Denied

If you get an error saying your access is denied, you are not allowed to use this "official" installation of caiman; instead, see the setup guide for how to install and run it locally.

Troubleshooting ERROR: Unable to locate a modulefile for 'caiman'

Your module environment path does not include CLAS12 modules; run the following then try again: 

module use /scigroup/cvmfs/hallb/clas12/sw/modulefiles

When you run caiman, you'll need to give it a database name, for example, rgl (Run Group L): 

caiman -d rgl
This command will open VIT (see below) for the rgl database. Once you exit VIT by pressing q then y to confirm, the dashboard website will be regenerated and deployed.

Warning

Please avoid leaving VIT open for long periods of time: open it, make your changes, then quit.

  • Only one user at a time can run caiman, to prevent two users from making conflicting changes at the same time.
  • Use the dashboard website if you want to be able to see tasks for longer periods of time.

Terminology

Here are some terms used throughout; see design notes for software details.

Term Description Relevant Links
Task A unit of work with a name, state, additional attributes, and possible dependence on other such units
Predecessor A task that must be completed before a given task
Successor A task that may be started only after completing a given task
Report A table with rows of tasks and columns of their attributes; the tasks are sorted and may be filtered
Dashboard Read only front-end web view of the tasks and their progress Dashboard Home
TaskWarrior Command-line task manager, the back-end; tasks for a dashboard are stored in a SQLite database, managed by TaskWarrior Home Page & Documentation
VIT Interactive terminal interface editor for TaskWarrior, a read/write front end that runs when you run caiman Home Page & Documentation
caiman Runs VIT then deploys the dashboard; also the name of this repository Home Page & Documentation

VIT Usage

The rest of this guide will focus on using VIT, which allows you to view and edit tasks. When you first open VIT (by running caiman), all of the tasks are shown in a table called a 'report'; see below for how to change how/which they are displayed (i.e., change reports).

Each row of a report is a single task; press the <up> and <down> arrow keys to move up and down. Its columns are:

Column Description
Project Called 'Category' on the dashboard; a task can have only one project
Description Task title
Tags Called 'Subsystem(s)' on the dashboard; a task can have zero or multiple tags
Start If the task has been started, the start date
End If the task is done, the end date
ID Integer ID number; it's just a short number and will change as tasks are started and completed (cf. UUID)
Predecessors List of task IDs which must be completed before this task can be started
Urgency TaskWarrior's way of calculating how 'urgent' a task is; see below

Viewing a Task

Press <enter> to view a task's attributes; press <enter> again to return to the report view.

Each row is an attribute for this task, which has a 'Name' and a 'Value'; for example, the attribute named 'Contact Person' should have a value that is the person to contact for this task.

Some attributes are specific to TaskWarrior, such as 'ID' and 'Description', while others we have added specifically for CLAS12 Calibration usage, such as 'Contact Person'.

Note

If a certain attribute's value is empty, it will not appear in this detailed view at all.

TaskWarrior-specific attributes:

Name Description
ID Integer ID number; it's just a short number and will change as tasks are started and completed (cf. UUID)
Description Task title, along with any annotations (timestamped comments)
Status 'Completed' if done, otherwise 'Pending'
Project Called 'Category' on the dashboard; a task can have only one project
This task is blocked by Predecessor tasks IDs that are not yet done
This task is blocking Successor task IDs
Entered When the task was created
Start If the task has been started, the start date
End If the task is done, the end date
Last modified When the task was last modified
Tags Called 'Subsystem(s)' on the dashboard; a task can have zero or multiple tags
Virtual tags Ignore this
UUID Universally Unique Identifier: an immutable ID number unique to this task (cf. ID)
Urgency TaskWarrior's way of calculating how 'urgent' a task is; see below

CLAS12 Calibration-specific attributes:

Name Description
Contact Person The contact person for this task
Input Data The data needed to perform this task
Outcomes The resulting output of this task
Validation How to validate or what to check
Documentation Source Relevant documentation for this task
Details Any additional details

Urgency

The 'urgency' calculation is shown at the bottom of a task's details. Urgency is a number based on various task properties, such as number of successor tasks, where a higher number means "more urgent". We use this urgency to sort tasks, since task ID is mutable, and sorting by UUID makes no sense.

There is no way to "force" a certain ordering of tasks, we can only sort them based on some parameter, and urgency is supposed to order tasks roughly in the order we should do them for optimal efficiency.

See TaskWarrior's Urgency Documentation, if you're curious.

Task Actions

Now let's cover how to mark a task as begun, done, and more. Many of these actions require you to press <up> and <down> to select a certain task, then press a key or two.

Task Begin

Marking a task as started means that it is currently in progress. If a task is not started yet, it is either considered 'ready' (i.e., it can be started any time), or 'blocked' by some unfinished predecessor task.

Warning

Do not start a task without completing all of its predecessor tasks.

  • Press b to mark a task as 'begun' (a.k.a., 'started')
    • A prompt will appear at the bottom of your screen; press y to confirm or n to cancel
    • The start date will appear in the 'Start' column, and will be the current date (and time)
  • You may press b again to 'stop' a task; the start date will be removed, i.e., as if the task were never started
  • If you want to edit the start date, see the expert guide

Task Annotate

At any time you may add a comment to a task, e.g.,

X is done, but Y is delayed because of Z

Such comments are called 'annotations' in TaskWarrior; they are timestamped and will appear on the dashboard.

  • Press A to add an annotation to a task
    • Do not confuse this with a (lowercase), which will instead add a new task (press <esc> to exit the prompt at the bottom)
    • You will be prompted to enter the annotation at the bottom of the screen; press <enter> when done (or <esc> to abort)
  • To remove an annotation, press E then follow the directions
  • You may do this for any task, regardless of its status

Task Done

  • Press d to mark a task as 'done' when the task is completed
    • A prompt will appear at the bottom of your screen; press y to confirm or n to cancel
    • The end date will appear in the 'End' column, and will be the current date (and time)
    • Press <ctrl+l> to refresh the screen, so the 'Predecessors' column view gets updated correctly (don't fret if you forget, the dependencies are updated in the database, but the view in VIT does not update until you refresh the screen)
  • Successors of this task will have this task removed as a predecessor in the 'Predecessors' column
    • This is just how VIT displays information
    • The dependencies are still known in the database
  • If you need to mark a done task as 'not done':
    • Press m to enter 'modify' mode; a prompt will appear at the bottom of your screen
    • Type status:pending, then press <enter>
    • Press <ctrl+l> to refresh the screen
  • If you want to edit the end date, see the expert guide

Warning

An exception will be thrown if you attempt to mark a task as done if it has incomplete predecessor tasks.

How to Change Reports

You can change the 'report', which controls which tasks are shown and how much detail is included:

  1. Press the colon key (:) to start a command-line entry at the bottom of your window
  2. Type one of the following report names below
  3. Press <enter>
Report Name Description
all show all the tasks, sorted by 'Project', and by 'Urgency' for each 'Project'; this is the default
urgent same as all, but sort by 'Urgency' overall
ready show only tasks that are ready (i.e., not started)
active show only tasks that are actively in progress (i.e., started, but not completed)
completed show only tasks which have been completed

Note

The top-left corner of your window indicates which report is currently being shown.