This is an area that really needs mock screenshots to figure out whether
the application is going to meet users' needs. These requirements could
be met in lots of different ways, some of which would be completely
unacceptable because the UI wasn't comprehensible.

**Temporal Queries Use Cases and** **Requirements**

The use cases only include specifying the query. They should include
executing the query, too.

+------------+---------------------------------------------------------+
| **Use Case | **Temporal Query --** **Base + Offset**                 |
| Name**     |                                                         |
+------------+---------------------------------------------------------+
| **Use      | 1.  A banker wants to query for biospecimens which were |
| scenario** |     collected when patients were over the age of 30.    |
+------------+---------------------------------------------------------+
| **Use Case | caTISSUE_Suite_UC_TQ_1                                  |
| ID**       |                                                         |
+------------+---------------------------------------------------------+
| **Primary  | Banker                                                  |
| Actor**    |                                                         |
+------------+---------------------------------------------------------+
| **Brief    | Define a query using **an** **unknown** base date plus  |
| Des        | some defined temporal offset                            |
| cription** |                                                         |
+------------+---------------------------------------------------------+
| *          | Actor navigates to the Advanced Search page             |
| *Trigger** |                                                         |
+------------+---------------------------------------------------------+
| **Pre-co   | Successful navigation to the Advanced Search page       |
| nditions** |                                                         |
+------------+---------------------------------------------------------+
| **Flow of  | 1.  The actor initiates the formulation of a new query  |
| Events**   |     by                                                  |
|            |                                                         |
|            |     a.  Specifying the object whose date is to be used  |
|            |         (base*)*                                        |
|            |                                                         |
|            |     b.  Specifying the object expressing the offset     |
|            |         (ex. calendar event point)                      |
|            |                                                         |
|            |     c.  Specifying the operation between the base and   |
|            |         the offset (typically '+' or '-')               |
|            |                                                         |
|            |     d.  Specifying a predicate.                         |
+------------+---------------------------------------------------------+
| **Post     | Success Condition: the query is formulated.             |
| Co         |                                                         |
| nditions** | Error Condition: Invalid object (base)                  |
|            |                                                         |
|            | Error Condition: Invalid object (offset)                |
|            |                                                         |
|            | Error Condition: Invalid operation -- the operation is  |
|            | not compatible with the operands                        |
|            |                                                         |
|            | Error Condition: Implausible predicate -- predicate     |
|            | does not make sense (comparing the difference between   |
|            | two dates to an absolute date for example).             |
+------------+---------------------------------------------------------+
| **Branch   | If a validation error occurs, the system throws an      |
| Points**   | exception, displays an error message and re-displays    |
|            | page for data entry.                                    |
|            |                                                         |
|            | a.  Invalid Base Object: respecify base object (return  |
|            |     to step 1a)                                         |
|            |                                                         |
|            | b.  Invalid Offset Object (object type is not           |
|            |     compatible with operation): Respecify base object   |
|            |     (return to step 1b)                                 |
|            |                                                         |
|            | c.  Invalid Operation: Respecify operation (return to   |
|            |     step 1c). Both base object and offset object should |
|            |     have data types that are compatible with the chosen |
|            |     operation.                                          |
|            |                                                         |
|            | d.  Implausible predicate: Respecify predicate (return  |
|            |     to step 1d) or respecify operation (Return to step  |
|            |     1c)                                                 |
+------------+---------------------------------------------------------+
| **Related  |                                                         |
| Use        |                                                         |
| Cases**    |                                                         |
+------------+---------------------------------------------------------+

Biospecimen resource staff and scientists often need to obtain
information about participants, specimens, or other data elements in the
context of time. For example, there may be a need to find specimens
collected from breast cancer patients under the age of forty, regardless
of their actual absolute dates of birth or specimen collection.
Similarly, users may wish to find specimens that have been collected or
manipulated within a certain span of time (e.g. serum specimens from the
same patient collected at least 1 year apart), regardless of absolute
dates.

+------------+---------------------------------------------------------+
| **Use Case | **Temporal Query -- Base + Base**                       |
| Name**     |                                                         |
+------------+---------------------------------------------------------+
| **Use      | -   Find all specimens that are to be collected today.  |
| S          |     (Requires calculation involving registration date   |
| cenarios** |     and calendar event point)                           |
|            |                                                         |
|            | -   Obtain a patient sample that is more than one year  |
|            |     after end of therapy but less than 2 years          |
+------------+---------------------------------------------------------+
| **Use Case | caTISSUE_Suite_UC_TQ_2                                  |
| ID**       |                                                         |
+------------+---------------------------------------------------------+
| **Primary  | All approved users                                      |
| Actor**    |                                                         |
+------------+---------------------------------------------------------+
| **Brief    | Define a query using an operation on two absolute (but  |
| Des        | unknown) dates                                          |
| cription** |                                                         |
+------------+---------------------------------------------------------+
| *          | Actor navigates to the Advanced Search page             |
| *Trigger** |                                                         |
+------------+---------------------------------------------------------+
| **Pre-co   | Actor is a valid user of the system.                    |
| nditions** |                                                         |
|            | Successful navigation to the Advanced Search page       |
+------------+---------------------------------------------------------+
| **Flow of  | 1.  The actor initiates the formulation of a new query  |
| Events**   |     by                                                  |
|            |                                                         |
|            | ```{=html}                                              |
|            | <!-- -->                                                |
|            | ```                                                     |
|            | a)  Specifying the first object whose base date is to   |
|            |     be used (base1)                                     |
|            |                                                         |
|            | b)  Specifying the second object whose base date is to  |
|            |     be used (base2)                                     |
|            |                                                         |
|            | c)  Specifying the operation between the base and the   |
|            |     offset (typically '-')                              |
|            |                                                         |
|            | d)  Specifying a predicate. The predicate is based on   |
|            |     comparisons between two absolute quantities (for    |
|            |     example minutes, hours, or days). ???               |
+------------+---------------------------------------------------------+
| **Post     | Success Condition: the query is formulated.             |
| Co         |                                                         |
| nditions** | Error Condition: Invalid base object                    |
|            |                                                         |
|            | Error Condition: Invalid offset object                  |
|            |                                                         |
|            | Error Condition: Invalid operation                      |
|            |                                                         |
|            | Error Condition: Implausible predicate                  |
+------------+---------------------------------------------------------+
| **Branch   | If a validation error occurs, the system throws an      |
| Points**   | exception, displays an error message and re-displays    |
|            | page for data entry.                                    |
|            |                                                         |
|            | a.  Invalid Base Object (object type incompatible with  |
|            |     operation): Respecify base1 object (Return to step  |
|            |     1a)                                                 |
|            |                                                         |
|            | b.  Invalid base2 object (object type incompatible with |
|            |     operation): Respecify base2 object (return to step  |
|            |     1b)                                                 |
|            |                                                         |
|            | c.  Invalid Operation - Respecify operation (return to  |
|            |     step 1c). Both base1 and base2 should have data     |
|            |     types that are compatible with the chosen           |
|            |     operation.                                          |
|            |                                                         |
|            | d.  Invalid predicate -- Respecify predicate (return to |
|            |     step 1d) or respecify operation (return to step 1c) |
+------------+---------------------------------------------------------+
| **Related  |                                                         |
| Use        |                                                         |
| Cases**    |                                                         |
+------------+---------------------------------------------------------+

**Requirements**

+------+------------------+--------------------------------------------+
| **   | **Summary**      | **Requirements**                           |
| ID** |                  |                                            |
+------+------------------+--------------------------------------------+
| T    | Predicate        | It must be possible to specify (possibly   |
| Q_01 | between          | computed) predicates between temporal      |
|      | attributes of    | attributes of two? different objects       |
|      | different        |                                            |
|      | objects          | For example: specify a predicate between   |
|      |                  | participant date of birth and specimen     |
|      |                  | collection event                           |
+------+------------------+--------------------------------------------+
| TQ   | Temporal         | Temporal computations between two absolute |
| \_02 | computations     | dates should produce coherent results. The |
|      | between two      | subtraction of an absolute date from       |
|      | absolute dates   | another should result in a certain         |
|      |                  | positive number of time units if the       |
|      |                  | minuend occurs later than the subtrahend,  |
|      |                  | and should result in a negative number if  |
|      |                  | the minuend occurs before the subtrahend.  |
|      |                  | Addition of two absolute dates is          |
|      |                  | semantically nonsensical.                  |
+------+------------------+--------------------------------------------+
| T    | Temporal         | The result of this computation is always   |
| Q_03 | computations     | an absolute date. The addition of N time   |
|      | between an       | units to an absolute date should produce   |
|      | absolute date    | an absolute date later than the original   |
|      | and a number     | (offset by N time units). A subtraction    |
|      | representing     | should produce an absolute date earlier    |
|      | time units       | than the original (offset by N time        |
|      |                  | units). In the case of subtraction, N is   |
|      |                  | always the subtrahend.                     |
+------+------------------+--------------------------------------------+
| TQ   | Minimal time     | The minimal time unit for temporal         |
| \_04 | unit             | computations shall be the minute. The user |
|      |                  | interface, however, should allow the       |
|      |                  | expression of time in other units (months, |
|      |                  | weeks, days, etc.) when specifying         |
|      |                  | queries, as deemed appropriate.            |
+------+------------------+--------------------------------------------+
| TQ   | Temporal         | The system must distinguish temporal       |
| \_05 | predicates       | predicates and treat them as such based on |
|      |                  | data type. For example, using the '\<'     |
|      |                  | operator to compare two dates infers that  |
|      |                  | the first operand occurs earlier than the  |
|      |                  | second if the condition is true.           |
+------+------------------+--------------------------------------------+
| T    | Computed values  | Values computed as a result of an          |
| Q_06 | displayable      | operation (for example computing the       |
|      |                  | difference between two dates) should be    |
|      |                  | displayable in a column in the results     |
+------+------------------+--------------------------------------------+
| T    | Generic ordinal  | Although requirements (TQ_01 -- TQ_06)     |
| Q_07 | values           | discuss temporal values specifically, the  |
|      |                  | functionality herein should be extensible  |
|      |                  | to arbitrary ordinal values.               |
+------+------------------+--------------------------------------------+