---
title: "build_timeline"
---

[< Back to Reference](../reference.qmd) | [View source](https://codeberg.org/usrbinr/tidychain/src/branch/main/R/build_timeline.R#L55)

# `build_timeline()`

Build Formula Creation Timeline

## Usage

```r
build_timeline(xlsx, include_formulas = TRUE)
```

## Arguments

| Argument | Description |
|----------|-------------|
| `xlsx` | An xlsx_workbook object from `parse_xlsx()`, or a file path. |
| `include_formulas` | Logical. If TRUE (default), joins formula text from the worksheet. Requires reading the xlsx file. |

## Value

A tibble containing:

- `creation_order`: Position in calcChain (1 = first formula created)

- `cell_ref`: Cell reference (e.g., "B5")

- `sheet_name`: Sheet name

- `row`: Current row number

- `col`: Column letter

- `formula`: The Excel formula (if include_formulas = TRUE)

- `is_late_addition`: TRUE if formula was created after cells below it

- `order_vs_row`: Difference between creation order rank and row rank
(positive = created later than row position suggests)

- `file_created`: File creation timestamp (if available)

- `file_modified`: File last modified timestamp (if available)

## Description

Creates a timeline showing the order in which formulas were created in an
Excel workbook. This helps understand how a spreadsheet evolved and can
reveal formulas that were added later (potential patches, fixes, or
suspicious additions).

## Details

The timeline is based on Excel's calcChain.xml, which records the order
formulas were added to the workbook. This order persists even when rows
are moved, making it useful for:

- **Audit trails**: See how a model evolved over time

- **Debugging**: Find formulas added as patches or fixes

- **Quality assessment**: Orderly creation suggests planned development

- **Forensic analysis**: Late additions may indicate manipulation

Understanding "Late Additions"

A formula is flagged as a "late addition" if it was created after formulas
that currently appear below it in the spreadsheet. This can indicate:

- A fix or patch added after the original model was built

- A row inserted between existing formulas

- Potential data manipulation (in forensic contexts)

## Examples

```r
## Not run: 
# Build timeline from file
xlsx  dplyr::filter(is_late_addition)

## End(Not run)
```

