# Modeling methods

Vintage models three outcomes, called the **modeled outputs**: **credit loss**, **payoff** (a loan paid off in full), and **prepayment** (a partial prepayment on a loan that continues). Each output can be measured from more than one combination of fields. Each combination is a **method**, lettered A, B, or C in Vintage's order of preference.

You do not choose a method. Vintage works out, loan by loan, which methods your data supports and uses the earliest letter available. The Review screen tells you which method it used for how many loans, which it skipped, and why. Every method and the exact fields it needs are listed below.

## What every method needs

Every method for every output also needs the **universal base**, present on the loan itself:

- a usable **Loan ID**,
- **Snapshot Month**,
- **Current Balance**, and
- a **term**: Term (Months) or Maturity Date.

The term is part of the base for every output because a loan whose lifetime is undefined can never enter the modeling curves. Review refuses to call such a loan ready for anything, so its coverage figures stay honest about what the curves will include.

## How requirements are read

- A method's requirement is a list of **clauses**. A clause is satisfied when **at least one** of its listed fields is present and usable.
- A field marked **preferred when available** makes the method more accurate but never blocks it.
- **Event-shaped fields** are read across the whole portfolio. These are the fields that describe something happening: charge-off amounts and flags, recoveries, payoff and prepayment flags and amounts, the explicit charge-off and payoff dates, and the closure fields that feed a measure. A loan's lack of a charge-off record means nothing happened to it, not that data is missing. So such a clause is satisfied when the field exists **anywhere** in your data, in this upload or the accepted portfolio, and a performing loan with no charge-off still counts as ready and contributes to the loss curve.
- **Base and measurement fields** (the universal base, the term, and the schedule fields) must be on the loan itself.
- Method selection is deterministic and can differ from loan to loan.

## Credit loss

| Method | Needs | Notes |
|---|---|---|
| **A: Direct net loss** | Net Charge-Off Amount | The loss after recoveries, as reported. |
| **B: Gross charge-off** | Charge-Off Amount | Recovery Amount preferred when available. |
| **C: Explicit event** | Charge-Off Flag, or a Loan Status or Closure Reason value you classified as charged off | Signal only. Never makes a loan ready for credit loss on its own. |

**Method C names the event but carries no loss amount.** A charge-off recorded only as a flag or status cannot contribute a loss magnitude, so it makes **no** loan ready for credit loss. Those loans stay excluded, and counted, until an amount-bearing field (Net Charge-Off Amount or Charge-Off Amount) exists in your data. Vintage never counts a flag-only charge-off as a loss of zero.

A **typed transaction ledger** supplies a charge-off amount too: a Transaction Amount column on a file whose Transaction Type has a value you classified as a charge-off is read exactly as a Charge-Off Amount column would be.

Charge-off fields can come from a Transaction file as well as from Snapshot fields. When both report the same quantity for the same loan in the same month, the snapshot figure is used and the ledger figure is set aside, never added. See [Charge-offs and recoveries](/concepts/charge-offs-and-recoveries/).

## Payoff (full prepayment)

| Method | Needs | Notes |
|---|---|---|
| **A: Direct event** | Payoff Flag or Prepayment Flag | Payoff Amount preferred when available. |
| **B: Closure classification** | Loan Status or Closure Reason | Payoff Amount preferred when available. |

Both methods read your **value classifications**: a flag value you marked as the event, or a status value you marked *paid off*, counts as a payoff. An unclassified value is never guessed, which is why a classifiable column's values must all be classified before you can continue past Column Mapping.

Payoff Amount, from a Snapshot or a Transaction file, refines either method. Without it, a payoff returns the loan's whole remaining balance. With it, the payoff returns the reported amount, capped at the balance left after that month's scheduled principal.

## Partial prepayment

| Method | Needs | Notes |
|---|---|---|
| **A: Direct partial** | Partial Prepayment Amount or Unscheduled Principal Amount, **plus** Scheduled Principal Due or Scheduled Principal Paid | A reported unscheduled amount still needs the reported schedule to be measured against. |
| **B: Actual vs. scheduled** | Actual Principal Paid **and** Scheduled Principal Due or Scheduled Principal Paid; **or** Actual Payment Amount **and** Scheduled Payment Amount for the same month | Counts every dollar of principal paid above schedule. |

Method B's second form serves a book that reports payment totals rather than the principal split. The difference between two reported totals is pure principal, because the interest is in both figures and cancels:

$$
\text{Actual Payment Amount} - \text{Scheduled Payment Amount} = \text{Actual principal} - \text{Scheduled principal}
$$

In words: the extra cash collected beyond the scheduled payment is extra principal. A scheduled payment of $1,200 and an actual payment of $1,700 in the same month mean $500 of unscheduled principal. That is a measurement of figures you reported, not a reconstruction. It is the only use Vintage makes of payment totals; a payment total on its own says nothing about principal.

**There is no Method C for partial prepayment.** Vintage never reconstructs an amortization schedule, from balances, from an interest rate, or from a payment amount, to infer a prepayment.

### The schedule basis every speed needs

A prepayment speed is measured against the scheduled principal a loan reported, so every speed needs a reported **schedule basis**: Scheduled Principal Due or Scheduled Principal Paid (on a snapshot or a transaction ledger), or a Scheduled Payment Amount together with an Actual Payment Amount for the same month.

- A loan **with** a schedule basis but with neither Method A nor Method B still belongs in the speed measure. Full-payoff detection covers every loan, so a loan that never paid off is a measured zero. What it cannot show is partial prepayment, and the screen says so: prepayment speeds for these loans reflect full payoffs only.
- A loan **without** a schedule basis is excluded from the speed measure entirely, even if it reports a direct prepayment amount. It still counts in the credit-loss curves, which do not need a schedule.

The full speed math is in [Prepayment speeds](/concepts/prepayment-speeds/).

## How the methods compare

**Preference order is not accuracy.** Several methods measure the same thing equally well, and Vintage never recommends adding fields that would only move your loans from one to another at the same accuracy. Vintage never describes your own reported figures as estimated, inferred, or derived from a payment schedule.

- **Credit loss, A and B** are equally accurate whenever recoveries are reported. Vintage sums a loan's gross charge-offs, subtracts the recoveries it reports, and books the result at the month of the charge-off, which is exactly what it does with a reported net figure.
- **Payoff, A and B** are the same measurement. Both read your own classification of the value; neither is inferred.
- **Partial prepayment, A and B** are equally accurate and differ in scope. A counts what your servicer labelled a prepayment; B counts every dollar of principal paid above schedule, so it also catches unlabelled curtailments.

**The one accuracy nudge:** Gross charge-offs with **no Recovery Amount column anywhere in your data** are the one case that overstates loss, because the whole gross amount books as the loss. Review then asks for a Recovery Amount column, as an addition to the method you already use, and names a Net Charge-Off Amount column as the equally accurate alternative. In a book that does report recoveries, a charged-off loan with no recovery value recovered nothing; that is a measured zero, and it never triggers the ask.

## Fields may arrive on a typed ledger

A Transaction file with a **Transaction Type** column and one generic **Transaction Amount** column has each row's amount routed by the kind you classified that row's code as. A recovery row's amount is read as a Recovery Amount, a payoff row's as a Payoff Amount, a regular payment row's as an Actual Payment Amount, and so on. A ledger that carries payment and schedule facts therefore satisfies the same clauses a snapshot would, and its loans enter the speed measure on the same terms. See [Standard fields](/reference/standard-fields/#typed-transaction-ledger).

## Origination is informational

Origination never blocks an upload. Vintage uses Origination Date and Original Loan Amount when you provide them. Otherwise, for a loan first seen **after** your organization's earliest snapshot month, it estimates the origination date from that first month and the original balance from the first balance it sees, and flags the loan **Estimated origination**. A loan already present in your **earliest** snapshot month with no origination date cannot be aged and is excluded from the age-indexed curves, counted, with a nudge: a two-column file of Loan ID and Origination Date unlocks those loans. See [Origination and term](/concepts/origination-and-term/).

## Where you see methods in Vintage

On the Review screen, each modeled output's card shows:

- how many loans are ready, and which method or methods Vintage will use, each with its share of loans stated over its own denominator ("8 of 60 loans · 13.3%");
- on demand, a coverage detail: for each method in play, the fields its loans draw from and the column each value came from;
- when an output is under 50% ready, an options guide listing every method in preference order, with each field marked as present or missing and its share of loans.

See [Reviewing before you finalize](/uploading/reviewing-before-you-finalize/).

## Related

- [Standard fields](/reference/standard-fields/)
- [Reviewing before you finalize](/uploading/reviewing-before-you-finalize/)
- [Preparing your data](/getting-started/preparing-your-data/)
- [Credit loss measurement](/concepts/credit-loss-measurement/)
- [Prepayment speeds](/concepts/prepayment-speeds/)
- [Payoffs and exits](/concepts/payoffs-and-exits/)