> For the complete documentation index, see [llms.txt](https://codifi-fdm.gitbook.io/codifi-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://codifi-fdm.gitbook.io/codifi-docs/cross-platform-features/ripple/value-formulas.md).

# Value Formulas

Value formulas — also called **Calculated Fields** — automatically compute a field's value based on other data in the Record, its parent, its children, or the Project. They appear as read-only-by-default fields to the user, though users can override them by typing a value.

> **Reminder:** value formulas only fill in **empty** fields. If a user types a value, the formula stops running for that field. See the [Ripple overview](/codifi-docs/cross-platform-features/ripple.md#how-ripple-works) for the full behavior.

***

## Basic Math & Conversions

Ripple supports all standard arithmetic on numeric fields.

| Operation          | Description                         | Example use                                    |
| ------------------ | ----------------------------------- | ---------------------------------------------- |
| Addition (+)       | Add two or more values              | `Total Artifacts = Lithics + Ceramics + Other` |
| Subtraction (−)    | Subtract values                     | `Net Depth = Bottom Elevation − Top Elevation` |
| Multiplication (×) | Multiply values                     | `Volume = Length × Width × Depth`              |
| Division (÷)       | Divide values                       | `Artifact Density = Count ÷ Area`              |
| Modulo (%)         | Remainder after division            | Day-of-week math                               |
| Round              | Round to N decimal places           | Display area as `12.35` (2 decimals)           |
| Ceil / Floor       | Round up or down to nearest integer | Whole-number bag counts                        |
| Absolute Value     | Remove negative sign                | Elevation difference (always positive)         |
| Square Root        | Mathematical square root            | Standard deviation calculations                |
| Power              | Raise to an exponent                | Area from radius: `π × r²`                     |

#### Example: Converting Excavation Volume

An excavation unit measured in centimeters needs its volume in cubic meters.

**Fields:** Length (cm) = 100, Width (cm) = 100, Depth (cm) = 45

```
Volume (m³) = (Length / 100) × (Width / 100) × (Depth / 100)
            = 1.0 × 1.0 × 0.45
            = 0.45 m³
```

#### Example: Artifact Density per Square Meter

Automatically calculate how many artifacts were found per square meter.

**Fields:** Artifact Count = 127, Unit Area (m²) = 4.0

```
Density = round(Artifact Count / Unit Area, 1)
        = round(31.75, 1)
        = 31.8 artifacts/m²
```

***

## Text & Concatenation

Ripple can build text values by combining fields, adding labels, and formatting strings.

| Operation             | Description                                         | Example                                    |
| --------------------- | --------------------------------------------------- | ------------------------------------------ |
| `concat`              | Join text values together                           | `"Site " + Site Number + ": " + Site Name` |
| `upper`               | Convert to ALL CAPS                                 | `STATE CODE → "NM"`                        |
| `lower`               | Convert to lowercase                                | Normalize search terms                     |
| `titleCase`           | Capitalize Each Word                                | `"red river valley" → "Red River Valley"`  |
| `trim`                | Remove leading/trailing spaces                      | Clean up imported data                     |
| `substring`           | Extract part of a string                            | First 3 chars of a site number             |
| `replace`             | Swap text within a string                           | Replace `/` with `-` in IDs                |
| `contains`            | Check if text includes a word                       | Does description contain "historic"?       |
| `startsWith`          | Check beginning of text                             | Does ID start with "LA"?                   |
| `length`              | Count characters in a string (or items in an array) | String length, array length                |
| `split` / `join`      | Break apart or recombine text                       | Join artifact types with commas            |
| `padStart` / `padEnd` | Add leading/trailing characters                     | Pad catalog # to 6 digits: `"000042"`      |

#### Example: Auto-Generated Catalog Number

Build a standardized catalog number from Project info and a sequence.

**Fields:** State Code = "NM", Project Number = "2026-047", Sequence = 42

```
Catalog Number = State Code + "-" + Project Number + "-" + padStart(Sequence, 5, "0")
               = "NM-2026-047-00042"
```

#### Example: Descriptive Field Label

Combine site name and type for a display label.

**Fields:** Site Name = "mesa verde overlook", Site Type = "Habitation"

```
Display Label = titleCase(Site Name) + " (" + Site Type + ")"
              = "Mesa Verde Overlook (Habitation)"
```

***

## Dates & Time

Work with dates for scheduling, duration tracking, and field activity logs.

| Operation                | Description                     | Example                              |
| ------------------------ | ------------------------------- | ------------------------------------ |
| `today` / `now`          | Current date or datetime        | Default *Date Recorded* to today     |
| `dateDiff`               | Days/months/years between dates | Field season duration in days        |
| `dateAdd`                | Add time to a date              | Due date = Start + 30 days           |
| `formatDate`             | Display date in a custom format | `"April 10, 2026"` or `"2026-04-10"` |
| `year` / `month` / `day` | Extract part of a date          | Group Records by survey year         |
| Date Range support       | Start/End date pair fields      | Field season: Mar 15 – Nov 1         |

{% hint style="warning" %}
**Date fields with Date Range format:** the field's `.value` is a `{StartDate, EndDate}` object, not a single date. Pass `.fieldStartDate` (or `.fieldEndDate`) into `dateDiff` / `dateAdd` instead of `.value`, otherwise the formula receives an object and silently misbehaves.
{% endhint %}

#### Example: Days in Field

Calculate how many days a survey phase has been running.

**Fields:** Survey Start Date = 2026-03-15, Survey End Date = 2026-04-10

```
Days in Field = dateDiff(Survey End Date, Survey Start Date, "days")
              = 26 days
```

#### Example: Formatted Record Timestamp

Show when a Record was last updated in a human-readable format.

```
"Recorded on " + formatDate(now(), "MM/DD/YYYY")
→ "Recorded on 04/10/2026"
```

***

## Lookups & Cross-Record References

One of Ripple's most powerful features is the ability to look up values from other Records in your Project hierarchy. A child Record can display its parent's site name. A parent can show a count of its children. A feature can reference a value from the Project Details.

| Lookup direction    | What you can access                     | Example                                         |
| ------------------- | --------------------------------------- | ----------------------------------------------- |
| **Parent ↑**        | Any field on the parent Record          | Show parent Site Name on each Feature           |
| **Project ↑↑**      | Any field on Project Details            | Show Project Number on every Record             |
| **Children ↓**      | Fields from child Records               | List all artifact types from child Records      |
| **Siblings ↔**      | Records that share the same parent      | Count how many features in this site            |
| **Ancestors ↑↑↑**   | Walk up the hierarchy (max 10 levels)   | Show the root site for any deeply nested Record |
| **Descendants ↓↓↓** | Walk down the hierarchy (max 10 levels) | Count all items in the entire sub-tree          |

#### Example: Display Parent Site Name on a Feature

Each Feature Record automatically shows which Site it belongs to.

```
Parent Site = Parent Record → "Site Name"
```

**Result:** `"LA 12345 — Mesa Top Pueblo"` — updates automatically if the feature is moved to a different site.

#### Example: Pull Project Number onto Every Record

Every Record in the Project shows the master Project number.

```
Project Number (on any archetype) = Project → "Project Number"
```

**Result:** `"NM-2026-047"` — one source of truth: change it on Project Details and it ripples to every Record.

***

## See Also

* [Spatial Formulas](/codifi-docs/cross-platform-features/ripple/spatial-formulas.md) — distance, area, perimeter, and coordinate calculations
* [Aggregation Formulas](/codifi-docs/cross-platform-features/ripple/aggregation-formulas.md) — sum, count, and average across repeater rows or child Records
* [Operations Reference](/codifi-docs/cross-platform-features/ripple/reference.md) — every operator with arguments and return types