On this page
Separate the source clock from the reporting grid
The source dates shown in this guide identify documentation checks on 22 October 2026, not original publication dates. Begin with the source event or sample timestamps exactly as received. Record timezone context, clock precision, duplicate timestamps, out-of-order rows, and the first and last timestamp that the file actually contains. Then write a separate expected grid, such as every five minutes between two stated boundaries. A row on the grid is not proof that a source observation existed there.
| Evidence | Record | Do not infer |
|---|---|---|
| Observed timestamp | Exact source value and timezone context | A missing point means zero |
| Expected grid | Interval, origin, and inclusive bounds | The grid was the producer clock |
| Coverage | First and last observed source time | The file covers the whole period |
| Duplicates | Count and resolution rule | Duplicate rows are repeated samples |
| Clock quality | Offset, precision, and ordering | Local time can be compared as UTC |
Keep a presence column beside the value column. A source row with value zero, an absent interval, and a row withheld by a filter are three different observations. That distinction is especially important when a downstream rate or average will be calculated.
Choose boundaries before calculating bins
A resampler needs a frequency and a boundary policy. State whether a bin is left-closed or right-closed, how its label is chosen, and whether partial bins at the beginning or end are retained. If a daylight-saving transition or a timezone conversion is relevant, keep the original offset and the normalized timestamp in separate columns. Do not let a library default become an undocumented part of the dataset contract.
| Decision | Synthetic choice | Review question |
|---|---|---|
| Frequency | Five minutes | Why is this interval appropriate? |
| Origin | Start at an explicit UTC instant | Is the anchor documented? |
| Closed side | Left closed, right open | Which boundary owns an event? |
| Partial bins | Retain and flag | Are edge values comparable? |
| Timezone | Preserve offset and normalized time | Did conversion shift a boundary? |
| Duplicate rows | Hold for owner rule | Was an aggregate silently chosen? |
The pandas, (opens in a new tab) documentation describes resampling and methods such as aggregation and filling, but it cannot decide the meaning of your interval. Record the operation name and its parameters in the review sheet so another reader can reproduce the representation without mistaking it for a new measurement.
Label every aggregation and fill as a transformation
For each output bin, retain source-row count, source-time span, aggregate function, and a status such as observed, empty, filled, or edge. A sum over a bin means something different from a last value, mean, forward fill, or interpolation. A fill can make a table look complete while still leaving the original gap unresolved. Never replace the source series in place.
| Output state | Allowed evidence | Safe wording |
|---|---|---|
| Observed | At least one source row in bin | Contains source observations |
| Empty | No source row in bin | No source observation recorded |
| Filled | Rule, limit, and predecessor recorded | Derived value, not observed |
| Aggregated | Rows, function, and units recorded | Reduced from source rows |
| Edge | Partial-bin bounds and status | Boundary coverage is partial |
Run the worksheet on a synthetic series
Synthetic source and review result
source_time | value | source_state
00:00Z | 4 | observed
00:03Z | 5 | observed
00:12Z | 0 | observed
00:17Z | 7 | observed
expected_grid=5m; bounds=00:00Z..00:20Z; empty_bins=00:05Z,00:10Z
00:00Z..00:05Z | aggregate=9 | observed
00:05Z..00:10Z | value=blank | empty
00:10Z..00:15Z | aggregate=0 | observed
00:15Z..00:20Z | value=7 | observed| Check | Synthetic result | Hold condition |
|---|---|---|
| Presence | Two bins have no source row | Blank converted to zero |
| Aggregation | First bin combines two rows | Sum treated as a raw sample |
| Observed zero | 00:12Z is a real source row | Zero confused with absence |
| Bounds | Last bin ends at stated boundary | Trailing period inferred |
| Reproduction | Grid and rule written beside result | Only output values retained |
The fixture is deliberately small and synthetic. Add cases for duplicate timestamps, a daylight-saving boundary, a late row, and an interval that begins before the requested range. Each case should produce a status and an owner question, not an unqualified number.
Keep resampled evidence separate from downstream decisions
A timestamp grid can document coverage and transformations. It cannot establish sensor accuracy, operational uptime, a scientific conclusion, or the suitability of a collection for a particular use. Preserve the raw timestamps, transformation parameters, and unresolved intervals together, then let a domain owner decide what a gap means.
Pair this guide with export timestamps and timezones for timestamp provenance and the data provenance log for transformation history. After a supported non-health scope, authority to describe the collection, and a controlled time-series packet are established, the qualified appraisal request path may be a preparation step. It does not resample data, infer missing values, create a quote, match a buyer, or grant a license.
Takeaways
- Write the observed timestamps and expected grid as separate evidence.
- Choose interval boundaries and timezone rules before computing bins.
- Label empty, observed, filled, aggregated, and edge output states.
- Keep synthetic fixtures and transformation parameters with the result.
- Do not treat a complete grid as proof that the source was complete.