Date-to-Age Converter

Purpose

To convert a date value to an age (in days or years) using a text-based date value and a specified base date.

Type Name

‘date_to_age’

Definition Syntax

‘[value_key]:[date_format]:[decimals]: [base_date] : [express_in]’

where:

  • ‘value_key’ denotes the key mapping to the text-based date value in the value dictionary. This key should be the name of a column in your raw data or a model parameter.
  • ‘date_format’ is the format of your dates. Allowed values are ‘dd-mm-yyyy’,‘dd/mm/yyyy’, ‘yyyy-mm-dd’ and ‘yyyy/mm/dd’
  • ‘decimals’ is the number of decimals to round the age to.
  • ‘base_date’ is the base date from which the age will be calculated. This can be either a fixed date, e.g. ‘28-12-2023’ or a key that maps to a valid date value in the value dictionary. Alternatively, you can specify ‘now’ to use the run-time date (see warning below!). If you are specifying a date explicitly or extracting it from the value dictionary, the format of the date must be the same as specified in parameter ‘date_format’.
  • ‘express_in’ - this should be either ‘years’ or ‘days’ to specify whether the age should be expressed in years or days.
Note

From Version 0-2-1 onwards, the, base date can be either a string representation of a date, e.g. ‘28-12-2023’ or the key word ‘now’ (as explained above), or the name of a key mapping to a value such as ‘28-12-2023’ in the key-value dictionary.

Example 1

‘cond_survey_date : yyyy-mm-dd : 1 : 2023-12-28 : years’

This will take the value mapped to key ‘cond_survey_date’ in the value dictionary and convert the text-representation of the date to a .NET date value presuming that the date is in the format ‘yyyy-mm-dd’ (e.g. ‘2024-02-13’). JCass will then calculate the fractional number of years elapsed between this date and the specified base date ‘2023-12-28’. This value will then be rounded to 1 decimal before assigning the result to the JFunction key in the value dictionary.

Example 2

‘cond_survey_date : yyyy-mm-dd : 1 : f_base_date : years’

This will take the value mapped to key ‘cond_survey_date’ in the value dictionary and convert the text-representation of the date to a .NET date value presuming that the date is in the format ‘yyyy-mm-dd’ (e.g. ‘2024-02-13’). JCass will then calculate the fractional number of years elapsed between this date and the date value held against the key ‘f_base_date’ in the value dictionary. It is expected that the value mapping to this key will be a string in the required format, e.g. ‘2023-12-28’. This value will then be rounded to 1 decimal before assigning the result to the JFunction key in the value dictionary.

Comment

The way the age in YEARS is calculated is as follows:

  1. The text value is converted to a .NET datetime object
  2. The number of days elapsed is calculated by taking the total number of days elapsed between the date value calculated in Step 1 and the specified base date (or the current date-time of the computer if base date is ‘now’).
  3. The number of years elapsed is calculated as the number of days elapsed (calculated in Step 2) divided by 365.25
  4. The final number of years elapsed is calculated by rounding the results from Step 3 to the specified number of decimals.
Important

If you are specifying the base date as ‘now’ (i.e. using the date of the model run), you should take note of the consequences of using this function to initialise model inputs. The values returned by this function will be dependent on the date and time when you run your model. This means that - depending on the number of decimals you round the age to - the values you get on a certain day may be different from those you get a few weeks, days or even hours later!

Depending on how you use the age-values calculated with this function in your model, these effect may mean that two identical model setups may give slightly different results when they are run at different times.

For this reason, it is recommended that you always specify the base date explicitly.