Resource ledger report

CLEM.Reporting.ReportResourceLedger

A ledger style report of every transaction for a given resource.

A resource ledger can be thought of as akin to a bank statement or ledger of all transactions. Every time a resource is added or removed by an activity, the details can be recorded. The report contains a gain and loss column to report when the resource is added or lost from the system with losses reported as negative for ease of analysis. The ledger holds all the information about the changes in the resource amount through the simulation and can be further analysed.

A single instance of this report component is added in each CLEM simulation branch of the simulations tree. This will ensure each farm records transactions. Each component needs the same name to ensure all transactions are placed in the same table in the Data Store.

The following parameters are used to define this activity and entered under the Properties tab in the user interface

The following general parameters are available

This option determines how the transaction will be provided in the ledger report. Two options are available:

This option will report separate columns for both gain and loss for each transaction. Only one of the columns will contain a value indicating the type of transaction. Any losses will be reported as a negative value. This approach is used for all conversions and pricing displayed with the transaction.

Each transaction will report either a loss or a gain. This approach was used rather than providing positive and negative values in the transaction that are difficult to sum and summarise.

This option will report a column indicating whether the transaction was a gain or loss and a column representing the amount. With this report style a single amount column will be provided for pricing and any converters associated with the resource (Type is assumed constant from the Type column).

This style is suited to report pivots for analysis

The name of a single resource group for which all transactions are to be reported.

Report all losses as a negative value. This can help in data analysis accounting.

Include the amount converted to all Resource units converters provided.

This parameter entry box allows you to include additional properties in the output.

For all transactions not ruminants the following entry is reported and any additional properties of the LastTransaction object can be included.

[Resources].{NameOfResourceGroup}.LastTransaction.{PropertyName}

For the Ruminant herd ledger the LastTransaction object contains a LastIndividualChanged component where you can access any of the Ruminant properties.

[Resources].{NameOfResourceGroup}.LastTransaction.LastIndividualChanged.{PropertyName}

Note: Intellisense is not provided to help you locate properties in this entry box.

The following parameters relating to finances are available

Include the amount converted to price if resource pricing is included.

Include the financial year with each transaction.

The following parameters relating to the Transaction category are available

This parameter defines the number of levels of a transaction category, with levels delineated by a full stop ".", to be reported as separate columns in the output

A value of 0 will report the label as provided (no levels)

A value >0 will report the specified number of levels as columns

Blank entries will be provided if the label does not supply the number of levels required.

This parameter provides the names of the output columns to be used for each level. This is provided as a comma (",") delimited list with no spaces allowed in the names (spaces will be stripped).

A default format of Category[level] (e.g. Category1) will be used as the column name if any level name is blank or insufficient names are provided for the number of levels reported

The following parameters define which properties of the individual ruminant are reported with the transaction. This allows the user to reduce the output database size by ignoring unneeded properties in the Herd ledger which reports the entry and exit of every individual in during the simulation and can therefore become large when simulating large herds.

These option will only be visible when the Ruminant herd is selected as the resource group to report.

This option determines how the age of the ruminant will be reported:

Age is not included in the report.

Age in months will be included.

Age is reported as a decimal number representing the years. For example a 15 month old individual is 1.25 years old.

Age is reported as a whole number representing the years. For example a 15 month old individual is 1 years old and will become two years old at 24 months.

A range of common Ruminant properties can be included using the following switches

  • Include ruminant adult equivalent

  • Include ruminant breed

  • Include sale flag (sale reason) as category

  • Include change direction (1 gain/purchase/birth, -1 sale/death)

  • Include ruminant class

  • Include ruminant ID

  • Include ruminant location (paddock name)

  • Include herd name as relates to column

  • Include ruminant sex

  • Include ruminant weight

Additional properties can be reported using the Custom variables parameter in General (see above)

This report will create a table in the output database with the same name as used in the simulation tree to describe this component.

The following columns are provided in the table

The Date the transaction occurred. In CLEM all dates will be the last day of the month (except for all initialisations which will happen on the first day of the month).

The following columns will be written when using the Gain and Loss report style.

The amount of the resource gained (added) in this transaction

The amount of the resource lost (removed) in this transaction

The following columns will be written when using the Type and Amount report style.

The type of transaction (either a gain or loss to the resource type)

The amount of the resource in the transaction

If he resources being report have Resource units converters associated with them the converted values will be included in the ledger as separate columns. These will include a "gain" and "loss" column or just the amount depending upon the report style selected.

The resource used in the transaction

The name of the activity performing the transaction

The name of a resource that this activity relates to that can be used to group transactions.

This entry will be empty (Blank) if the resource used in the transaction is the only resource of interest

This is NOT the resource being used in the transaction. For example, assume we have an irrigation task (Crop task activity) and associated cost (Crop fee activity), both associated with producing Wheat in our simulation. The HumanFoodStore.Wheat resource would be reported as the RelatesToResource in the ledger so that we can do an analysis of all resources used to produce the wheat (e.g. labour, finance) .

This column will report the Ruminant herd for transactions relating to ruminants where the herd is not defined elsewhere (e.g. Ruminant ledger). For simplicity, this is left blank if only one herd is considered in the simulation. This column may also include the ruminant class for ease of reporting.

A category label used to identify this transaction.

See Transaction category for full details.

This is used when you have multiple simulations reported in the DataStore

This is used to determine which CLEM component (Zone) the transaction was from. This is used when you have multiple farms or a Market in your simulation.

This report generates the variables required depending upon the options selected in the user interface.

All reporting is performed on the LastTransaction property of the required ResourceGroup assumed to be in the Resource holder named [Resources].

A range of examples are provided below for (a) ruminants, (b) using the gain loss column style and (c) using the Type and Amount columns style

All values provided in curly braces need to be replaced, including the braces (e.g. {Name of resource group} would become Ruminants for the a herd named Ruminants)

This report can be manually created using an APSIM Report.

Reporting variables

(a) Ruminant ledger

The LastTransaction property holds additional information (ExtraInformation property) providing animal details.

[Clock].Today as Date

[Resources].{Name of resource group}.LastTransaction.LastIndividualChanged.ID as uID

[Resources].{Name of resource group}.LastTransaction.LastIndividualChanged.Breed as Breed

[Resources].{Name of resource group}.LastTransaction.LastIndividualChanged.Gender as Sex

[Resources].{Name of resource group}.LastTransaction.LastIndividualChanged.Age as Age

[Resources].{Name of resource group}.LastTransaction.LastIndividualChanged.Weight as Weight

[Resources].{Name of resource group}.LastTransaction.LastIndividualChanged.AdultEquivalent as AE

[Resources].{Name of resource group}.LastTransaction.LastIndividualChanged.SaleFlag as Category

[Resources].{Name of resource group}.LastTransaction.LastIndividualChanged.HerdName as RelatesTo

[Resources].{Name of resource group}.LastTransaction.LastIndividualChanged.PopulationChangeDirection as Change

(b) gain and loss column style

[Resources].{Name of resource group}.LastTransaction.Gain as Gain

[Resources].{Name of resource group}.LastTransaction.Loss * -1 as Loss

The -1 in the previous line is used to report all losses as negative numbers

(c) type and amount column style

[Resources].{Name of resource group}.LastTransaction.TransactionType as Type

[Resources].{Name of resource group}.Amount as Amount

To report amount as negative for loss type transactions use:

[Resources].{Name of resource group}.AmountModifiedForLoss(True)as Amount

Additional details for (b) and (c)

[Resources].{Name of resource group}.LastTransaction.Activity.Name as Activity

[Resources].{Name of resource group}.LastTransaction.RelatesToResource as RelatesTo

[Resources].{Name of resource group}.LastTransaction.Category as Category

 

[Resources].{Name of resource group}.LastTransaction.ResourceType.Name as Resource

if markets exist

[Resources].{Name of resource group}.LastTransaction.Activity.CLEMParentName as Source

 

To report the price of the resources in the transaction (pricing must be set up)

for (b)

[Resources].{Name of resource group}.LastTransaction.ConvertTo("$gain","gain", True {if reporting loss as -ve values, otherwise False} ) as Price_Gain

[Resources].{Name of resource group}.LastTransaction.ConvertTo("$loss","loss", True {if reporting loss as -ve values, otherwise False}) as Price_Loss

or for (c)

[Resources].{Name of resource group}.LastTransaction.ConvertTo("$gain", {True {if reporting loss as -ve values, otherwise False}) as Price_Amount

 

To report a specified unit conversion of the resources in the transaction (must be set up)

for (b)

[Resources].{Name of resource group}.LastTransaction.ConvertTo({converter name},"gain", True {if reporting loss as -ve values, otherwise False} ) as {name}_Gain

[Resources].{Name of resource group}.LastTransaction.ConvertTo({converter name},"loss", True {if reporting loss as -ve values, otherwise False}) as {name}_Loss

or for (c)

[Resources].{Name of resource group}.LastTransaction.ConvertTo({converter name}, {True {if reporting loss as -ve values, otherwise False}) as {name}_Amount

 

The report is updated whenever a transaction occurs and uses the following reporting frequency.

Reporting frequency

[Resources].{Name of resource group}.TransactionOccurred

See also