Labour allocation examples
The labour allocation examples are designed to help you add labour to your simulation whether tracking family labour in a small-holder farm or tracking hired labour requirements. These simulations are provided in the CLEM_example_labour simulation file. You can use these example descriptions as a walk-through tutorial for setting up and exploring the outcomes of your own simulation.
Values used in examples are purely fictitious and are only intended as representative values in the example. Some figures may not be realistic.
All activities have the required labour available, and this examples does not consider the impact of labour shortfalls on farm outcomes.

This simulation applies labour to the range of activities already discussed in the cropping example.
This example introduces:
- Labour resource and Labour type components
- Labour requirement components
- Labour filter groups for specifying individuals
- Labour pricing and Labour price group for payments
- Labour availability list
- Pay hired labour activity

A Crop data reader (named FileCrop_Maize) is used to read the file of maize harvests (space delimited APSIM crop output file name FileCrop_Maize.prn)
A Crop data reader (named FileCrop_Vegetables) is used to read the file of all vegetable (tomato and cucumber) production (space delimited APSIM crop output file name FileCrop_Vegetables.prn)

This example assumes you understand the details of the Cropping examples for Land, Finances, Product store and associated activities.
In this example Labour is provided to perform the harvest of the maize crop. Separate Male and Female Labour types are provided with a Labour availability list providing the days per month for each labour type as Labour availability items.

The Labour resource holder is placed as a child of the Resource holder and contains all individuals in the simulation. This component also has some settings and we will not be including cohorts, or allowing individuals to age over time.

Labour type components are provided below the Labour resource and specify an individual or group of individuals with the same details (cohort). The name of each of these components is used to identify the individual(s). This example represents a small family farm with a husband (male), wife (female), two children (ChildFemale and ChildMale) and some hired labour. The age, sex and number of individuals is assigned for each.

The Labour availability list is also provided as a child component of Labour resource. This allows us to set the amount of time (in days) each individual (or cohort) is available for each time-step (assumed monthly for this example). A Labour availability item is provided for each individual on our farm with a Labour group used to identify the individual. We use age to identify children (<18 years old), and the IsHired flag to identify hired labour. The Male and Female are identified by their name, but given they have the same availability this could have been a Labour Group with two filters (Age > 18 and IsHired = false), in a single Labour availability item.

A Labour pricing component is also provided to ensure we know how much to pay for the hired labour. A single Labour price group is provided to allocate a price per day for our hired labour.
If there was no hired labour, or we we not interested in the finance, this component could be omitted.


A single Labour task activity with a Labour requirement and Labour group is included to represent schooling of the children. While not exactly labour for a task, this activity will remove labour (time in days) from the amount the children have to work on the farm. Children are set to attend school for 17 days of the month (of the 20 days available).
To see the effect of needing children for farm activities before school we can move the school activity to below Manage Vegetables or the Tomato Paste folder by selecting the activity (School) and hitting (CTRL/CMD) Down/Up Arrow.

Each crop (tomatoes and cucumbers) in the Manage Vegetables (Manage crop) activity has a Labour requirement. This is placed directly below the Manage crop product component as a special case representing the labour required for harvesting. Later, in Manage Maize, we will see how other crop tasks are added to account for additional labour.
Two Labour groups are provided to specify the individuals that can perform the task. These are nested to dictate the order of trying to take the labour needed for the task of harvesting. First labour is provided from children, and if more is needed than available, the Female individual is needed to provide the remainder.
The same rules apply for harvesting the cucumbers. Rather than recreate the filter groups and increase complexity in managing the simulation, a Linked labour group is provided that points to the rules specified in the tomato crop. This is only the filters, and the cucumber harvest Labour requirement specifies the cucumber specific details.

Managing maize is similar to vegetables with respect to labour.
First, there is a Labour requirement directly below the Manage crop component (called HarvestLabour). Like the manage vegetables labour, this provides a nested structure where Males are first requested for labour, followed by females, and finally if labour is still required we use the hired labour. This is a special type of Labour type where the Hired property has been checked. This allows easy access, but also is used by activities such as Pay hired labour. These individuals also do not age, even if ageing is permitted by other individuals on the farm. This is an example of "catching" the labour needed by a final group that can be set large enough to convert any shortfall into labour we can track with financial expense.
Managing Maize also requires a range of other tasks which use labour on the farm. Unlike harvest which can be assumed as a child of the Manage crop component, we need to identify the other tasks with Crop task activity components. In this example we provide prepare, plant, weed and transport actions, with Crop harvest timers to define the timing with respect to the harvest dates determined from the crop input file. The labour requirements used include any adult (Prepare), which is also used for Plant and Weed. Transport can only use hired labour and relieves the farm owners of this task.
Finally, we provide the labour needed to process tomatoes into tomato paste. There is a single Labour requirement as a child of the Process resource activity. This contains nested Labour groups defining the order in which labour will be requested for the activity. In this case the filers are females (sex = female) and then male (sex = male). If we think about this filter rule the task will first be performed by any female (Female or ChildFemale) and the order they are requested is based on the order their associated Labour type appears in the Labour resource holder, so female adult, followed by female child. If the females can't provide enough labour, then the males (adult, then hired, then child) are requested. In this case the Hired labour is included as they are also male. To avoid this we would add a Filter by property where IsHired isFalse.
For more details on specifying individuals for labour see Labour filter groups.

A Pay hired labour component is added to the activities. This activity requires an Activity fee component to specify the resource to be used for payment. In this case we state that it relates to the labour used metric of the parent component, we'll use Finances from the General account, and base the payment on the "per total charged" with a rate of measure of 1, or the total charged.
We can effectively pay our hired labour (labour used identifier) with any resource they accept. In that case we would change the Resource to use to any of our other resources from the list, let's say Maize stored in the OtherStore. We could pay a fixed amount in the time-step, proportional to the amount charged, or another per day rate (selecting the Measure to use property) and supplying the Rate per measure.
You may have noticed a problem with this approach in our example. The PayHired component appears after the Sell Maize component and so by the time we went to pay hired labour maize, it would be all sold, unless we added a reserve or proportion to sell. Alternatively, you could move the hired labour payment above the maize sales to ensure that if maize was available it would be used for payment before being sold. Of course this does not ensure there is always maize available for payment as hired labour may occur in months where no harvest takes place.

The reports provided with the example provide the model output needed. We can learn a lot about the simulation by looking through the reports and even note where things may not have gone as expected.

The Activities performed report provides a graphical display of the status of all activities during your simulation. A lot of information can be gained from displaying this report in the user interface or opened in a web browser in a separate window. We can learn the following about our simulation:
- Manage Maize and Manage vegetables are place holder activities with nothing specific to do each month but manage their child components so do not have a symbol displayed.
- We are able to see that the various crops are harvested in different months. The Manage crop product activities are performed every month as seen from the green or grey tick in every column. The columns with a green check mark indicate where a harvest took place. You can check that the harvest months correspond to your input data. Tomatoes are even harvested across multiple months.
- We can also see that the Sell Maize activity is performed every month, but only has something to do (sell maize) in the months where maize is harvested. If we look at the Sell tomato paste activity we see that the November salesInterval timer that only occurs in November each year is limiting when the Sell tomato paste activity is performed. Activities that are not performed because their timer was not active will display with a blank column.

The Labour requirements report provides a graphical display of where all labour was allocated in the simulation. Note, this is how labour is allocated and not the actual use of labour in the simulation.
- Five types of labour are provided in the simulation (named Male, Female, Hired, ChildMale and ChildFemale) and 12 activities performed accept Labour requirements with three not having any labour allocated.
- The Sell Maize, Sell Tomato paste, and Pay Hired activities are able to accept Labour requirement but none have been assigned in this simulation.
- Male labour is preferred for growing maize, but if insufficient, Female labour will be used, and then Hired. This is shown by the index displayed by each labour type beside an activity.
- Make tomato paste shows anyone might be needed with females asked first followed by all the males in the order they appear in the simulation tree.
The next three reports provide all transactions for Products, Finances and Labour. We will consider what we can determine from each

The automated CLEM Resource ledger report for the Products store provides every transaction that occurred during the simulation. Click on this report component. In the Properties tab you will see that only our ProductStore is set for reporting. Next click the Data tab to see what transactions were produced.
- You can see all the entries providing gains (resource came into the store) coming from the harvest activities (Grow maize crop, Grow cucumbers and Grow tomatoes) as well as the Process tomato paste activity that produces a gain for Tomato paste and a loss for the Tomatoes store as expected.
- Losses from the store were also produced by the two sell activities
- Loss converted to value (price in Price_Loss column) is also included. No Price_gain column was added as there were no purchase pricing provided.

The automated CLEM Resource ledger report for the Finances store provides every transaction that occurred during the simulation. Click the Data tab to see what transactions were produced.
- The ledger starts with the initial bank balance of $100
- All gains to the bank account come from the various sales of maize and tomato paste.
- Losses (or expenses) come form the months where jars are purchased for making tomato paste or hired labour was paid for.
- Loss converted to value (price in Price_Loss column) is also included. No Price_gain column was added as there were no purchase pricing provided.
- The category column uses the values provided in the simulation and allows us to group income and expenses into the various categories.

The automated CLEM Resource ledger report for the Labour store provides every transaction that occurred during the simulation. Click the Data tab to see what transactions were produced.
- All transactions are losses as we can't gain labour (other than buying hired labour, but this is in fact a labour source on the farm).
- We can see labour transactions are categorised as Harvest or Process based on the categories supplied.
- The resource column could be used to report on labour used by type (e.g. Male and Female)
- The amount of labour used for each activity changes throughout the simulation as a result of being based on crop harvested and amount of tomato processed which are responding to the input data.

The automated CLEM Resource balances report provides balances at the end of each month for the Labour, ProductStore and Finances stores as dictated in the Properties tab. Click the Data tab to see the monthly balances.
- The labour columns provide the remaining days available at the end of the month. We can see that there is no shortfall of labour in our simulation requirements, but some people do have labour available at the end of time-steps.
- Maize and Tomato balances are always zero as these are either sold or converted into tomato paste between the harvest and the end of the month.
- Tomato paste stores build up until sold in November each year
- The Cucumber store continues to increase. It is only now that we may realise we have a valuable resource that we have not sold during our simulation.
- The General_account column shows the bank balance. The overall increase suggests our maize and tomato paste farm is profitable. But, we also now realise we have not included any of the farm operating expenses.

The automated CLEM Resource shortfalls report provides presents every time a resource was in shortfall when requested.
- As expected from our ledger and balance reports the shortfall report is empty.
- This is a valuable report to check. The CLEM descriptive summary will also alert you when shortfalls occurred in your simulation.

A range of graphs are provided to show you how to set up APSIM graphs and present results.
See also