/
Calculated Filter (Temporal Queries)
Got feedback or spotted a mistake?

Leave a comment at the end of this page or email contact@krishagni.com

Calculated Filter (Temporal Queries)

Owned by Poornima Govindrao
Last updated: May 29, 2025 by Ashish Vishwakarma

Often one needs to perform queries based on calculated fields of dates or number fields.

Examples:

  1. Difference between collection time and date of birth (age at collection)

  2. Difference between collection time and received time (warm ischemia time)

  3. Difference between frozen time and received time

  4. All specimens collected "today", "last week" or "last month"

Demonstration of a Temporal Query:

https://youtu.be/VFNAhwMgw7A

Temporal functions

When calculating the difference between two date fields or formatting a date to display in a specific format, there are two parts to consider and include “Parameterization”:

  1. Left-Hand Side: This includes the function and fields you wish to evaluate. For example:

    • Calculate 'Minutes':

      minutes_between(Specimen.customFields.additional_specimen_detail_form.cold_ischemia_end, Specimen.customFields.additional_specimen_detail_form.cold_ischemia_start)

    • To format a date:

      date_format(Participant.regDate, "%month_day% %month3% %year4%")

  2. Right-Hand Side: This represents the condition to check against. Examples include:

    • any

    • > 20

    • <= 50

    • 18 Jan 2017 (when using date format)

Function

Description

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 wella) 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: can be any form field or arithmetic expression whose result is of date type

  • range_type: possible values are 

    • last_cal_qtr: last calendar quarter

    • next_cal_qtr: next calendar quarter (new in v6.1)

    • last_qtr: last quarter

    • next_qtr: next quarter (new in v6.1)

    • last_cal_month: last calendar month

    • next_cal_month: next calendar month (new in v6.1)

    • last_month: last month

    • next_month: next month (new in v6.1)

    • last_week: last calendar week (new in v4.0)

    • next_week: next calendar week (new in v6.1)

    • current_week: this week (new in v4.0)

    • last_days: last N calendar days (new in v4.0)

    • next_days: next N calendar days (new in v6.1)

    • yesterday: yesterday's calendar date. Special form of last_days where N = 1

    • tomorrow: tomorrow's calendar date. Special form of next_days where N = 1 (new in v6.1)

    • today: today's calendar date (new in v4.0)

  • interval: a positive integer. Optional. When not specified, its value is assumed as 1

Date Range Temporal Filters Illustration: Assuming the present date as 15th March 2017

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

date_format(date_expr, format)

Outputs date/time field/expression value in desired format.

  • date_expr: Any valid AQL expression that yields date/time type result

  • format: Format of the output string and can be made up of following format specifier tokens.

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-20250515-065623.png

Only 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

Example 1: Age as of today 

Note: If the "date of birth" value is blank for the participant, the query results would be blank.

image-20250515-070657.png

Example 2: Age at collection

Note:

  1. This expression only works for "parent (New)" specimens.

  2. If the "date of birth" value is blank for the participant, the query results would be blank.

image-20250515-071157.png

Temporal Expression: "years_between( Specimen.extensions.SpecimenCollectionEvent.time, Participant.dateOfBirth) any"

Example 3: Age at collection

Note:

  1. This expression works for specimens at any level (New, Derived, and Aliquot).

  2. If the "date of birth" value is blank for the participant, the query results would be blank.

image-20250515-071234.png

Temporal Expression: "years_between( Specimen.spmnCollRecvDetails.collTime, Participant.dateOfBirth) any"

Example 4: Time difference between frozen and received time

image-20250515-071324.png

Example 5: Tissue specimens collected in the last 2 months

image-20250515-071519.png

Example 6: Calculating the sample amount

image-20250515-071735.png

Example 7: Count of specimens collected per month

image-20250516-021658.png

Example 8: Count of participants registered per month.

image-20250516-022239.png

Example 9: Count of specimens collected after a particular date

image-20250516-022339.png

Example 10: Age in years (rounded off)

Expression: round( years_between( Participant.regDate, Participant.dateOfBirth), 0) any
image-20250519-115107.png

 

Example 11: Age in years (rounded off) between 10-20 age

Expression: round( years_between( Participant.regDate, Participant.dateOfBirth), 0) between (10,20)
image-20250519-115541.png

Example 12: Number of participants enrolled and parent samples entered per week.

image-20250516-022611.png

Result view:

image-20250516-022910.png

Note: Select the count of participant and primary specimen in 'Aggregates' column to view the count in the result view.

Example 13: Finding percent from 2 numbers in custom form

image-20250516-134727.png

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 14: Calculating the initial cell value from the volume processed and initial concentration, where the volume processed and initial concentration are specimen custom fields.

image-20250516-134137.png

In the above expression,

  1. aj_specimen_form is the variable name of the custom form.

  2. initial_processing_volume and initial_cell_volume are the variable names of the volume processed and initial concentration custom fields.

 

Example 15: Average of 2 custom fields.

image-20250516-135438.png

In the above expression,

  1. 'skin_cancer_registration_custom_field_form' is the variable name of the form name.

  2. ‘number_field_1' and 'number_field_2’ are variable names of the custom fields.

  3. 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 

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/%22 ,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

 

Got feedback or spotted a mistake?

Leave a comment at the end of this page or email contact@krishagni.com