Filtering and sorting individuals

Filters

Filtering is used to define sub-groups of larger lists of individuals. This relates to defining labour, ruminants and other animals and is essential in determining which individuals an activity or process considers.

Filtering is based upon Filter group components that may include associated parameters (based on the specific task of group) and any number of individual Filter components. Each filter defines a rule using a property or method (only methods without required arguments, or additional details provided in the brackets) of the Resource type being filtered (e.g. age in labour, or breed in ruminants), an operator (e.g. equal to, or greater than) and a value to compare with. Each individual in the population is tested against this rule, and if the check is true, it will be included in the filter group. Filtering can also be performed on Attributes added to individuals with filtering possible on whether the attribute exists, or the additional value set with the attribute.

A filter group can contain any number of filters with each rule being additive such that all rules provided in a group must be met for an individual to be included. A group with no filters provided will return the entire population of individuals (e.g. no filtering). A filter group with conflicting properties (e.g. IsPregnant and IsSire associated with a female and male ruminant respectively) will return an empty list and will not provide a warning. As Filter groups are independent components, it is the user responsibility to ensure filters and filter groups identify the correct individuals and do not apply an activity to the same individual multiple times, unless that was the intention.

Sorting

Sort components allow for the ordering of any filtered groups of individuals. Sorting can be performed on a any of the properties, methods and attributes available for filtering and allows individuals at the top of the list to be provided first in management decisions with the option to sort ascending or descending. These components are placed within a Filter group and will be applied as we move down the list such that filtering can be applied multiple times.

A special case of Sort randomise allows you to randomise, or shuffle, the order of individuals. This is useful if you do not want any inherent order relating to the temporal creation of the list to be included (e.g. purchase or setup of the herd), but require a truly random selection of the filtered individuals.

When multiple sort components are provided in a Filter Group they will all be performed as a nested sort in the order they are specified in the simulation tree.

If we performed three sorts (sort by sex ascending, sort by age descending, and sort randomly) in our Filter group the resulting list of individuals would be grouped by females then males (f is before m in alphabet). Within each of these groups we would have the groups by age (assuming years old) from oldest to youngest with the order of individuals of each sex by age randomly assigned.

Limiting the number provided

The Take from filtered component specified the number of individuals to be returned from the filtering. A number of individuals or proportion of the final filter group can be specified. This component is placed within a Filter group.

 

Example simulation

An example simulation to help explore using filters, sorting and the number of individuals to return is provided in Examples\CLEM with your APSIM Next Generation installation. This example provides the list of checks performed to ensure filtering and sorting is working correctly.

For more details see