Convolve Function
Performs a discrete convolution of an inflow series with a time-based distribution curve.
How the Convolve Function Works
At its core, convolve() performs a discrete convolution. It takes an incoming stream of data, applies a time-based profile to it, and calculates the aggregate state for every period.
It automatically remembers how much volume enters in each period, calculates its age relative to today, applies your curve, and sums up the active survivors or remaining value from every past group to give you the total output.
The Underlying Math
While convolution is a purely mathematical concept, the easiest way to visualize it is through a classic SaaS retention cohort matrix:
Common Use Cases
Because convolve() is mathematically agnostic, you can use it for far more than just user cohorts. By changing what your inflow and curve represent, the function adapts to a variety of modeling scenarios:
- SaaS Retention: Inflow (New Signups) × Curve (Retention Rate) = Total Active Users
- Asset Depreciation: Inflow (Capital Expenditures) × Curve (Depreciation Schedule) = Net Book Value (Note: if you use useful life to model depreciation, we have another function
depreciatethat handles depreciation specifically.) - Expansion Revenue: Inflow (Base Tier Users) × Curve (Upgrade Probability) = Total Upgraded Accounts
- Inventory Management: Inflow (Units Produced) × Curve (Historical Sell-Through) = Remaining Inventory
- RSU Vesting Schedules: Inflow (New RSU Grants) × Curve (Distribution) = Agrregate Sum
Arguments
The function requires two primary series to run, and accepts an optional filter to pause incoming data.
Inflow (Required): The sequence of new inputs entering the system for each period. For example, if 100 units arrive in Period 0 and 200 arrive in Period 1, this array tracks those incoming batches.
Curve (Required): The distribution or decay curve applied to each inflow over time.
The distribution curve tracks the age or duration of the inflow, not the global calendar timeline.
- The first value is always the exact moment the inflow occurs (Age 0).
- The second value is the multiplier one period later (Age 1), and so on.
The curve always starts from the inflow's specific starting period. For example, if a batch of items only arrives in Period 3, the first value of your curve (Age 0) is applied to them right then in Period 3.
Filter (Optional): A boolean mask or condition to pause new inflows from entering the calculation. If you set this to 0 (false) for a specific period, no new inflows will be added, but your older, existing cohorts will continue to age and distribute normally.