Understanding Functions

Introduction

Functions are an advanced feature of Family Historian, and are used within Expressions that occur most commonly in:

For a full list see the Family Historian Help > Using Family Historian > Advanced Topics > Expressions and Contexts of Use.

Expressions are composed from two technical features:

  • Data References that often appear enclosed within percentage signs, e.g. %INDI.BIRT%
  • Functions that begin with an = sign (except when used within another Function), e.g. =RecordId()

Functions

A Function is a predefined computation that returns a value, often based on data supplied as Parameters. They are similar to 'functions' used in spreadsheets (such as MS Excel), macro languages (such as Visual Basic for Applications), or other programming languages. For example:

=ChildCount() supplies the Child Count, and =RecordId() supplies the Record ID for the current Record. See another example in Query Functions.

Any Parameters are enclosed in parentheses ( ) and separated with commas , as shown below:

=CalcDate(%INDI.BIRT.DATE%, 10, 3) returns a Date that is the Date of Birth plus 10 years and 3 months.

For full details see the Family Historian Help > Using Family Historian > Advanced Topics > Understanding Functions and then the subsidiary topics Functions (by category), Functions (all), Data Types, Operators, etc.

The Basics

Family Historian offers nothing equivalent to the Data Reference Assistant for constructing Functions, so they must be composed manually, and if Family Historian says that an Expression is invalid, then you must deduce where the error lies.

An alternative is the Utility ~ PSPad Family Historian Functions editor that helps you compose the Function syntax correctly before pasting it into an Expression.

Therefore, to start with it would be best to focus on the simpler Functions that have no Parameters until some experience has been gained.

Some Functions are more complex than others, and may take several Parameters. To use these, it would help to find an example in an existing Expression, and try to copy how it is used.

One common misunderstanding is whether to include or exclude the leading = sign on the Function name.
If the Function is NOT within the parentheses of another Function then the = sign is required.
If the Function is within the parentheses then the = must be omitted.
So for example:

=Year(%INDI.BIRT.DATE%) returns the Year of Birth of an Individual.

=CalcDate(Year(%INDI.BIRT.DATE%), 10) returns a Date that is the Year of Birth plus 10 years.

In the second example the Year() Function must NOT have the = sign prefix.

It is also essential that the parentheses ( ) are in matched nested pairs. In other words every opening parenthesis ( must have a matching closing parenthesis ).

This becomes quite difficult to check for complex nested Functions with multiple Parameters, that are larger than the Expression box display.

To overcome this it is a good idea to compose the complex Expression in a simple text editor such as Notepad, and build up the components bit by bit. At each step, copy and paste the Expression into Family Historian to check its syntax is valid, before adding the next component.

Estimation Functions

Several functions calcuate an Age or Date from recorded information. These include =AgeAt(), =EstimatedAgeAt(), =EstimatedBirthDate() & =EstimatedDeathDate().

=AgeAt() only uses the first Birth event Date and the supplied Date parameter. If either is a Range or Period with two Dates then only the earlier Date is used. If either Date is undefined then the function returns an empty string.

=EstimatedAgeAt(), =EstimatedBirthDate() & =EstimatedDeathDate() are far more sophisticated and use much more database information together with Tools > Preferences > Estimates to produce a value. They give precedence to Birth and Death events, but may also use Baptism, Christening, Burial, or Cremation events, or other facts for the individual and their relatives.

In reply to a question about these functions Simon Orde said:

These functions work hard to try to estimate a person's birth or death date based on known information about them. For birth date, for example, obviously, if a person's birth date is given, that trumps everything. But there may be other ways of calculating the date. For example, if the date of an event is known, and the person's age at the time of the event is also given, we can calculate the birth date precisely. If we can't do that, we will guess that an ordinary baptism or christening year, is the year of birth. If that doesn't give us a date, we will try to calculate a person's birth date from their date-of-death, from the dates of birth of any children they have (together with some reasonable assumptions about child-bearing ages for men and women), from the dates of their marriages if known (together with assumptions about marriage ages), from their parent's birth dates (together with assumptions about child-bearing ages for their parents), and from their spouse's birth dates.

If all that fails to deliver a usable result, we will look at the dates of any other events in the person's life that we may have. At this point (and only at this point), if we have a 'generation' figure, we will also start to go off and look at ancestors and descendants and see if we can estimate their birth dates. If we can, that will give us some kind of range (using reasonable estimates about child-bearing ages again), and we will also factor in the dates of the 'any other events' that we may have, as an additional check.

The 'number of generations' to check figure is used, but only for last-stage checking, if earlier checks failed to deliver a usable result.

Despite that, there are scenarios for which =EstimatedBirthDate() gives erroneous dates that may also affect =EstimatedAgeAt():

  1. If a fact has a Date and an Age then that may be used to establish the estimated Birth Date.
  2. If a Death event has a Before Date Range then that Date is set as the Earliest Birth Date.

In such scenarios, the Earliest Birth Date may be later than the Latest Birth Date, and both may be later than the Date of a life fact such as a Baptism or Census event.