metricengine.calculations.inventory

Inventory and COGS calculations.

This module defines inventory and cost-of-goods-sold calculations using namespaced registration. It returns ratios (0..1) by default for composability, with separate percent-returning wrappers if needed.

metricengine.calculations.inventory.cogs(opening_inventory, purchases, closing_inventory)[source]

Calculate Cost of Goods Sold (COGS) using the standard inventory formula.

COGS represents the direct costs attributable to the production of goods sold by a company. This includes the cost of materials and labor directly used to create the product, but excludes indirect expenses such as distribution costs and sales force costs.

Formula:

COGS = Opening Inventory + Purchases - Closing Inventory

Where:

Opening Inventory: Value of inventory at the beginning of the period
Purchases: Cost of additional inventory purchased during the period
Closing Inventory: Value of inventory at the end of the period

Parameters:

opening_inventory (FinancialValue[Money]) – FV[Money] - The monetary value of inventory at the start of the accounting period. Must be non-negative in most cases.
purchases (FinancialValue[Money]) – FV[Money] - The total cost of inventory purchased during the period, including freight and other direct costs.
closing_inventory (FinancialValue[Money]) – FV[Money] - The monetary value of inventory remaining at the end of the accounting period.

Return type:

FinancialValue[Money]

Returns:

FV[Money] - The calculated cost of goods sold. Returns FV(None) if any: input parameter is None, following the metricengine’s null propagation behavior.

Policy Behavior:

Inherits policy from input parameters (opening_inventory, purchases, closing_inventory) in that order of precedence
Falls back to context policy or DEFAULT_POLICY if no input has a policy
Maintains Money unit type for proper financial calculations

Examples

>>> # Basic COGS calculation
>>> opening = FV(1000)  # $1,000 opening inventory
>>> purchases = FV(5000)  # $5,000 in purchases
>>> closing = FV(1500)  # $1,500 closing inventory
>>> result = cogs(opening, purchases, closing)
>>> result.as_decimal()  # Decimal('4500.00')

>>> # With None values (null propagation)
>>> result = cogs(FV(1000), FV(None), FV(1500))
>>> result.is_none()  # True

>>> # Using engine calculation
>>> ctx = {
...     "opening_inventory": 200,
...     "purchases": 800,
...     "closing_inventory": 150
... }
>>> result = engine.calculate("cogs", ctx)
>>> result.as_decimal()  # Decimal('850.00')

Business Context:: COGS is a critical metric for: - Calculating gross profit (Sales - COGS) - Determining gross margin percentage - Inventory turnover analysis - Cost control and pricing decisions - Financial statement preparation (Income Statement)

Notes

This calculation assumes FIFO (First In, First Out) inventory method
Does not include indirect costs like overhead or administrative expenses
Negative COGS values are possible but may indicate data quality issues
All inputs must be in the same currency for meaningful results
The function handles None values gracefully by returning FV(None)

Inventory Metrics

metricengine.calculations.inventory.inventory_turnover(cogs, average_inventory)[source]

Inventory turnover = cogs / average_inventory

Return type:: FinancialValue[Ratio]

metricengine.calculations.inventory

Inventory Metrics

Cost Calculations