Deterministic publication DAPC outputs — publication_dapc

Creates and validates deterministic publication-layer contracts around existing authoritative DAPC results. The publication layer preserves, orders, fingerprints, reports, and exports discriminant coordinates, membership probabilities, diagnostics, cross-validation summaries, confusion data, and selected-K metadata without recomputing DAPC.

Usage

new_publication_dapc_spec(
  sample_id_column = "sample",
  population_column = "population",
  cluster_column = "cluster",
  axis_columns = c("LD1", "LD2"),
  selected_k = NULL,
  source_data_format = "tsv",
  version = "1.0.0"
)

validate_publication_dapc_spec(spec)

new_publication_dapc_output(
  spec,
  coordinates,
  membership,
  diagnostics = NULL,
  cross_validation = NULL,
  confusion = NULL,
  result_fingerprint,
  figure_binding = NULL
)

validate_publication_dapc_output(output, spec)

publication_dapc_caption(output, spec)

publication_dapc_report(output, spec)

Arguments

sample_id_column: Sample identity column in the discriminant-coordinate table.
population_column: Optional known-population column.
cluster_column: Optional inferred-cluster column.
axis_columns: Ordered discriminant-coordinate column names.
selected_k: Optional selected number of clusters.
source_data_format: Machine-readable source-data format, either "tsv" or "csv".
version: Specification version.
spec: A validated publication DAPC specification.
coordinates: Authoritative discriminant coordinates.
membership: Authoritative membership probability matrix or data frame with sample row names.
diagnostics: Optional authoritative per-K diagnostics.
cross_validation: Optional authoritative cross-validation summary.
confusion: Optional authoritative confusion matrix or long-form table.
result_fingerprint: Fingerprint of the authoritative DAPC result.
figure_binding: Optional publication figure-style binding.
output: A publication DAPC output.

Value

new_publication_dapc_spec() returns a fingerprinted PopgenVCFPublicationDAPCSpec. new_publication_dapc_output() returns a fingerprinted PopgenVCFPublicationDAPCOutput. Validation functions return TRUE invisibly. publication_dapc_caption() returns one manuscript-ready caption string, and publication_dapc_report() returns Markdown report lines.

Details

Coordinates are ordered deterministically by sample identity. Membership probabilities must align exactly with coordinate sample identities, contain finite values between zero and one, and sum to one for each sample. Optional figure-style bindings are validated for sufficient membership-group capacity. Specification and output fingerprints provide fail-closed mutation and drift detection.

Examples

spec <- new_publication_dapc_spec(selected_k = 2L)
coordinates <- data.frame(
  sample = c("sample_b", "sample_a"),
  LD1 = c(1.2, -0.8),
  LD2 = c(0.4, -0.2)
)
membership <- data.frame(
  cluster_1 = c(0.9, 0.1),
  cluster_2 = c(0.1, 0.9),
  row.names = c("sample_a", "sample_b")
)
output <- new_publication_dapc_output(
  spec,
  coordinates,
  membership,
  result_fingerprint = "example-dapc-result"
)
publication_dapc_caption(output, spec)
publication_dapc_report(output, spec)