---
title: "Coverage, provenance, and source limits"
description: "Understand publisher coverage, preserve provenance, and assess source limits."
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Coverage, provenance, and source limits}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(collapse = TRUE, comment = "#>", eval = FALSE)
```

The package retrieves public ArcGIS data; it does not host or archive the
records. This article describes the checked catalog's coverage and source
limits that matter when using the data.

## Bundled publishers

The package checks the following layers and searches each publisher's public
ArcGIS organization. Counts come from the bundled `datasets.json` and
`portals.json` registries.

| Publisher or jurisdiction | Checked layers | Live discovery |
| --- | ---: | :---: |
| Tampa | 20 | Yes |
| St. Petersburg | 7 | Yes |
| Clearwater | 6 | Yes |
| Hillsborough County | 8 | Yes |
| Pinellas County | 7 | Yes |
| Tampa Bay Regional Planning Council | 4 | Yes |

The 52 checked layers are a selection, not a publisher inventory. Live
discovery can find others, subject to portal indexing, availability, and
scan limits. The [discovery article](discovery.html) explains scan
completeness; the [catalog policy](https://github.com/Jaclenga/tampaBayOpenData/blob/main/docs/checked-catalog-policy.md)
records selection criteria, topic coverage, and layer-specific limits.

## Interpret source scope before analysis

Tampa's permits and development cases are active views, not complete
historical ledgers. Its `city-boundary` follows a shoreline representation,
not a legal survey, and `water-service-area` extends beyond city limits.
Clearwater's park buffers are not park footprints; its critical-assets layer
locates assets, not hazards. The Pinellas housing layer is a program inventory,
not all housing. Hillsborough transit routes are not a live schedule. The
regional planning council's storm surge layer is a historical planning model,
not current emergency guidance.

These layers alone do not establish legal boundaries, road restrictions,
service eligibility, or facility status. Comparable demographic coverage and
current flood and environmental coverage across all six publishers remain
limited. Inspect each layer's `scope_note` and source metadata for its own
limits. The current Tampa `fire-stations` source uses unqualified fields such
as `NAME`; older joined `GIS.GovServiceInfo.*` fields are unavailable.

```{r inspect-source}
library(tampaBayOpenData)

info <- tbod_dataset_info("construction-permits")
info[c("title", "source_url", "scope_note", "terms", "verified")]
```

Read `scope_note` and `terms` before analysis. `verified` records an endpoint
check, not feature freshness. A portal item's `modified` date can also differ
from its records' dates; `modified_source` distinguishes live item timestamps
from saved catalog snapshots.

Discovered items may change, disappear, or lack clear reuse terms. Inspect
their source metadata and publisher terms. The checked catalog remains
available offline if a live portal fails.

## Keep provenance with results

`tbod_provenance()` reads a record attached to a retrieved tibble or `sf`
object. It includes publisher and source URLs, portal and item ID when known,
validation status, query, retrieval time, row counts, integrity method, and
completeness. Direct URL retrieval has `not_checked` status.

```{r preserve-provenance}
projects <- tbod_get_dataset("development-cases", spatial = TRUE, out_sr = 4326)
source <- tbod_provenance(projects)
saveRDS(list(data = projects, provenance = source), "development-cases.rds")
```

Save provenance separately before transformations or exports that may discard
attributes. A finite subset is marked incomplete when more rows match.
Object-ID checks detect missing, duplicate, or unexpected records, but cannot
freeze live attributes across requests. See [retrieval and
downloads](retrieval.html) for the integrity methods.

## Monitoring and evidence

Twice weekly monitoring checks the 52 layers across all six publishers,
bounded live discovery, and county facility retrieval by descriptor and
stable ID. It also checks server projection to EPSG:4326. Retrievals request
at most two rows; scans inspect at most one service item per publisher. The
[test guide](https://github.com/Jaclenga/tampaBayOpenData/blob/main/tests/README.md)
describes these bounds and the manual live suite. The [validation
record](https://github.com/Jaclenga/tampaBayOpenData/blob/main/docs/validation.md)
dates completed checks; they cannot guarantee future availability or record
freshness.

## Cite the package and its data sources

For published work, cite the package version you used. R provides citation
text and BibTeX after installation:

```{r citation}
citation("tampaBayOpenData")
toBibtex(citation("tampaBayOpenData"))
```

Cite the original data publisher and dataset separately. `tbod_dataset_info(id)`
gives source details; `tbod_provenance(result)` records source and retrieval
time. The MIT license applies to the package software, **not** government
datasets. Publishers set their data terms. The package is independent of them
and of rOpenSci.

For implementation details, see the [architecture and research
basis](https://github.com/Jaclenga/tampaBayOpenData/blob/main/docs/architecture.md).