...
...
Often one needs to perform queries based on calculated fields of dates or number fields.
Examples:
Difference between collection time and date of birth (age at collection)
Difference between collection time and received time (warm ischemia time)
Difference between frozen time and received time
All specimens collected "today", "last week" or "last month"
This page describes the way to do it and different options available. For video training session, please refer to Wiki page Temporal Query (Video)
Creating a new temporal queryImage Removed
...
Info |
---|
title | Info: | Attribute names, functions, and operators are auto-completed once you start to type in the temporal expression window. |
---|
Demonstration of a Temporal Query:
...
Temporal functions
Expand |
---|
title | Click here to view functions... |
---|
|
Function | Description |
---|
months_between | To find the number of months between two dates. Example: month between registration date and visit date | minutes_between | To find the number of minutes between two timestamp fields. Example: time difference between frozen and received time | years_between | To find the number of years between two dates. Example: age at |
|
...
collectionThese functions can be used as below as well |
|
...
a) Days = minutes_between(d1, d2) / (24 * 60) b) Hours = minutes_between(d1, d2) / 60 c) Weeks = minutes_between(d1, d2) / (7 * 24 * 60) | current_date() | To get current date. Example: age as of today | round() | To round up calculations. In cases where integer values are expected, for example, temporal expressions related to dates, round() function ensures that stable integer results are obtained. Usage: round(expression, x) Here, the expression is the integer value result that is to be rounded. 'x' is the number of decimal places to be rounded up to or the number of digits after the decimal point that the expression should be rounded to. |
|
...
Example: round( years_between( current_date(), Participant.dateOfBirth), 0) any will keep 0 digits after decimal. | date_range(date, range_type, [interval]) | Allows to check for data that falls in the particular date range. |
|
...
...
...
...
| date_format(date_expr, format) | Outputs date/time field/expression value in desired format. Values in examples of below table are given w.r.t date/time 18th January 2017 16:45:33 date_format(Participant.regDate, "%month_day% %month3% %year4%") |
|
...
> "18 Jan 2017" Image AddedOnly those participants registered after 18 JAN 2017 will be displayed in the desired format. Similarly, you can use the other operators like < , = etc Specifier | Description | Example |
---|
%year4% | Four digit year | 2017 | %year2% | Two digit year | 17 | %month2% | Two digit month | 01 | %month3% | Three character abbreviation of month name | Jan | %month% | Month name string | January | %month_day% | Two digit day of month | 18 | %hour% | Hour of the day in 24 hour format 00-23 | 16 | %hour12% | Hour of the day in 12 hour format 01-12 | 04 | %minute% | Minute of the hour | 45 | %second% | Seconds of the minute | 33 | %meridian% | AM or PM | PM |
|
|
Examples of temporal queries
Expand |
---|
title | Click here to view examples... |
---|
|
Example 1: Age as of today | title | | If the "date of birth" value is blank for the participant, the query results would be blank. |
|
---|
...
Image Added Example 2: Age at collection |
title |
---|
Note: This expression only works for "parent (New)" specimens. If the "date of birth" value is blank for the participant, the query results would be blank.
|
|
...
Image Added Temporal Expression: "years_between( Specimen.extensions.SpecimenCollectionEvent.time, Participant.dateOfBirth) any" Example 3: Age at collection |
title |
---|
Note: This expression works for specimens at any level (New, Derived, and Aliquot). If the "date of birth" value is blank for the participant, the query results would be blank.
|
|
...
Image Added Temporal Expression: "years_between( Specimen.spmnCollRecvDetails.collTime, Participant.dateOfBirth) any" Example 4: Time difference between frozen and received time |
...
Image Added Example 5: Tissue specimens collected in the last 2 months |
...
Image Added Example 6: Calculating the sample amount |
...
Image Added Example 7: Count of specimens collected per month |
...
Image Added Example 8: Count of specimens collected after a particular date |
...
Image Added Example 9: Age in years (rounded off) |
...
Image Added Example 10: Number of participants enrolled and parent samples entered per week. Image Modified Result view: |
...
Image Added | title | | Select the count of participant and primary specimen in 'Aggregates' column to view the count in the result view. |
Example 11: Finding percent from 2 numbers in custom form |
---|
...
Image Added In the above example, number1 and number2 are two numeric fields defined in a form attached at 'Registration Forms' level. There is no % function in temporal queries, but the formula to find percent can directly used to calculate the same. Example 12: Calculating the initial cell value from the volume processed and initial concentration, where the volume processed and initial concentration are specimen custom fields. Image AddedIn the above expression, aj_specimen_form is the variable name of the custom form. initial_processing_volume and initial_cell_volume are the variable names of the volume processed and initial concentration custom fields.
Example 13: Average of 2 custom fields. Image AddedIn the above expression, 'skin_cancer_registration_custom_field_form' is the variable name of the form name. ‘number_field_1' and 'number_field_2’ are variable names of the custom fields. The CP (e.g. 'Skin Cancer Study') must be selected, for custom forms and fields.
|
Parameterized Temporal Filter
Temporal filters can be parameterized so that users can enter a range to dynamically filter the results. Below operators can be used in the temporal expression to make it parameterized:
Exists: to specify existence condition like age exists
Any: to specify don't care condition like age any
...
Date Range Temporal Filters Illustration
Assuming the present date as 15th March 2017
Expand |
---|
title | Click here to view expressions |
---|
|
Expression | Description | Date Range |
---|
date_range(Specimen.createdOn, last_cal_qtr, 2)
| Specimens created in last 2 calendar quarters | 1st July 2016 00:00 to 31st December 2016 23:59 | date_range(Specimen.createdOn, last_qtr, 2)
| Specimens created in last 2 quarters | 1st September 2016 00:00 to 28th February 2017 23:59 | date_range(Specimen.createdOn, last_cal_month, 3)
| Specimens created in last 3 calendar months | 1st December 2016 00:00 to 28th February 2017 23:59 | date_range(Specimen.createdOn, last_month, 3)
| Specimens created in last 3 months | 15th December 2016 00:00 to 14th March 2017 23:59 | date_range(Participant.regDate, today)
| Participants registered today | 15th March 2017 00:00 to 15th March 2017 23:59 | date_range(Participant.regDate, yesterday)
| Participants registered yesterday | 14th March 2017 00:00 to 14th March 2017 23:59 | date_range(Participant.regDate, last_days, 10)
| Participants registered in last 10 days | 5th March 2017 00:00 to 14th March 2017 23:59 | date_range(Participant.regDate, current_week)
| Participants registered |
|
...
in current week that is from ‘Sunday to Saturday'. If a query is run in the middle of the week, it will give results from 'Sunday to the current day’. | 12th March 2017 00:00 to 18th March 2017 23:59 | date_range(Participant.regDate, last_week, 2)
| Participants registered in last 2 weeks | 26th February 2017 00:00 to 11th March 2017 23:59 |
|
Calculated URLs
From v10.2 onwards, it is possible to configure URLs using temporal expression.
For the test server URL of participant overview page 'https://test.openspecimen.org/#/cp-view/6636/participants/176857/detail/overview', you need to configure the temporal expression as 'concat("https://test.openspecimen.org/#/cp-view/ " ,CollectionProtocol.id, "/participants/" ,Participant.id , "/detail/overview") != " "
For visit overview page URL https://test.openspecimen.org/#/cp-view/6636/participants/176857/visits/detail/overview?visitId=130492 you need to configure the temporal expression as concat("https://test.openspecimen.org/#/cp-view/" ,CollectionProtocol.id, "/participants/" ,Participant.id, "/visits/detail/overview?visitId=", SpecimenCollectionGroup.id) != " "
...
Below is the list of fields that are available to be used in the query
Field | Syntax |
Collection Protocol Identifier | CollectionProtocol.id |
Participant Registration Identifier | participant.id |
Participant Identifier | Participant.participantId |
Visit Identifier | SpecimenCollectionGroup.id |
Specimen Identifier | Specimen.id |