|
1 | | -#' Classify operational file types from observed resources |
| 1 | +#' Classify operational file types |
2 | 2 | #' |
3 | | -#' @description |
4 | | -#' Classifies observed digital resources into operational file types |
5 | | -#' using workflow-oriented classification profiles. |
6 | | -#' |
7 | | -#' Unlike simple MIME-type or extension lookups, the function is |
8 | | -#' designed for provenance-aware analytical and reconstruction |
9 | | -#' workflows where file meaning depends on operational context. |
10 | | -#' |
11 | | -#' The function supports lightweight operational classification for: |
12 | | -#' |
13 | | -#' - filesystem reconstruction; |
14 | | -#' - digital preservation review; |
15 | | -#' - repository analytics; |
16 | | -#' - synchronized workspace inspection; |
17 | | -#' - web archive inventories; |
18 | | -#' - and Heritage Digital Twin workflows. |
19 | | -#' |
20 | | -#' The current implementation provides a small set of built-in |
21 | | -#' profiles intended as operational starting points. |
22 | | -#' |
23 | | -#' These profiles are intentionally lightweight and extensible. |
24 | | -#' |
25 | | -#' Future versions may support: |
26 | | -#' |
27 | | -#' - user-defined profiles; |
28 | | -#' - YAML-based vocabularies; |
29 | | -#' - institutional review profiles; |
30 | | -#' - preservation-oriented classification schemes; |
31 | | -#' - workflow-specific semantic enrichment. |
32 | | -#' |
33 | | -#' The function is designed to work together with: |
34 | | -#' |
35 | | -#' - [read_snapshot()] |
36 | | -#' - [snapshot_to_reconstruction_context()] |
37 | | -#' - [create_record_set()] |
38 | | -#' |
39 | | -#' as part of layered provenance-aware reconstruction workflows. |
| 3 | +#' Classify observed resources into operational categories that support |
| 4 | +#' contextual reconstruction and Record Set derivation. |
40 | 5 | #' |
41 | | -#' @param x A `data.frame` or tibble containing observed resources. |
42 | | -#' |
43 | | -#' @param extension Character scalar identifying the column containing |
44 | | -#' file extensions. |
45 | | -#' |
46 | | -#' Defaults to `"extension"`. |
47 | | -#' |
48 | | -#' @param profile Character scalar defining the operational |
49 | | -#' classification profile. |
50 | | -#' |
51 | | -#' Current built-in profiles include: |
52 | | -#' |
53 | | -#' - `"r_development"` |
54 | | -#' |
55 | | -#' The `"r_development"` profile is designed for: |
56 | | -#' |
57 | | -#' - R package development; |
58 | | -#' - Quarto and R Markdown workflows; |
59 | | -#' - reproducible research repositories; |
60 | | -#' - analytical reporting pipelines. |
61 | | -#' |
62 | | -#' @return |
63 | | -#' A character vector containing operational file type |
64 | | -#' classifications. |
| 6 | +#' @description |
| 7 | +#' `classify_operational_file_type()` assigns observed files to |
| 8 | +#' broad operational categories such as code, data, documents, |
| 9 | +#' generated website files, and other artefacts. |
65 | 10 | #' |
66 | | -#' Typical output categories include: |
| 11 | +#' The current implementation provides an `"r_development"` profile |
| 12 | +#' derived from software development, reproducible research, |
| 13 | +#' and analytical repository workflows. |
67 | 14 | #' |
68 | | -#' - `"code"` |
69 | | -#' - `"markdown"` |
70 | | -#' - `"workspace"` |
71 | | -#' - `"data"` |
72 | | -#' - `"artifact"` |
73 | | -#' - `"document"` |
74 | | -#' - `"website_generated"` |
75 | | -#' - `"other"` |
| 15 | +#' The broader objective of operational classification is to |
| 16 | +#' introduce an intermediate semantic layer between filesystem |
| 17 | +#' observations and contextual reconstruction. |
76 | 18 | #' |
77 | 19 | #' @details |
78 | | -#' The function intentionally performs lightweight operational |
79 | | -#' classification only. |
| 20 | +#' In many digital collections, archives, and research |
| 21 | +#' environments, files participate in operational roles that |
| 22 | +#' cannot be inferred from directory structure alone. Examples |
| 23 | +#' include source materials, preservation masters, derivative |
| 24 | +#' artefacts, metadata records, rights documentation, analytical |
| 25 | +#' outputs, and publication-ready resources. |
| 26 | +#' |
| 27 | +#' Operational classification provides a lightweight mechanism |
| 28 | +#' for assigning observed resources to such workflow-oriented |
| 29 | +#' categories before higher-level contextualisation, Record Set |
| 30 | +#' construction, or semantic stabilisation takes place. |
| 31 | +#' |
| 32 | +#' Classification is currently based on extension patterns and |
| 33 | +#' workflow-specific heuristics. The function does not inspect |
| 34 | +#' file contents, infer authoritative media types, determine |
| 35 | +#' archival significance, or perform provenance reasoning. |
| 36 | +#' |
| 37 | +#' The resulting classifications should therefore be interpreted |
| 38 | +#' as operational hypotheses that support exploration, |
| 39 | +#' reconstruction, and contextualisation workflows rather than |
| 40 | +#' authoritative documentary assertions. |
| 41 | +#' |
| 42 | +#' Future classification profiles may support archival, |
| 43 | +#' audiovisual, heritage, research-data, and Records in Contexts |
| 44 | +#' workflows, where operational roles provide an important bridge |
| 45 | +#' between low-level filesystem observations and higher-level |
| 46 | +#' documentary interpretation. |
| 47 | +#' |
| 48 | +#' @param x A `data.frame` or tibble containing observed files. |
| 49 | +#' |
| 50 | +#' @param extension Character scalar identifying the column that |
| 51 | +#' contains file extensions. Defaults to `"extension"`. |
| 52 | +#' |
| 53 | +#' @param profile Character scalar defining the classification |
| 54 | +#' profile. Currently only `"r_development"` is implemented. |
80 | 55 | #' |
81 | | -#' It does not: |
| 56 | +#' @return |
| 57 | +#' A character vector of operational file type labels. |
82 | 58 | #' |
83 | | -#' - infer authoritative media types; |
84 | | -#' - inspect file contents; |
85 | | -#' - perform preservation risk assessment; |
86 | | -#' - infer documentary semantics; |
87 | | -#' - replace curatorial review. |
| 59 | +#' Possible values for the `"r_development"` profile include: |
88 | 60 | #' |
89 | | -#' Classification is based primarily on operational workflow |
90 | | -#' heuristics derived from file extensions and workflow profiles. |
| 61 | +#' \describe{ |
| 62 | +#' \item{code}{R source files.} |
| 63 | +#' \item{markdown}{Markdown, R Markdown, or Quarto files.} |
| 64 | +#' \item{workspace}{R workspace or serialized R objects.} |
| 65 | +#' \item{data}{Tabular spreadsheet or delimited data files.} |
| 66 | +#' \item{artifact}{Image artefacts.} |
| 67 | +#' \item{document}{PDF or word-processing documents.} |
| 68 | +#' \item{website_generated}{Generated website assets.} |
| 69 | +#' \item{other}{Files not matched by the selected profile.} |
| 70 | +#' } |
91 | 71 | #' |
92 | 72 | #' @examples |
93 | 73 | #' toy_files <- tibble::tibble( |
94 | | -#' extension = c( |
95 | | -#' "R", |
96 | | -#' "qmd", |
97 | | -#' "csv", |
98 | | -#' "png", |
99 | | -#' "woff2" |
100 | | -#' ) |
| 74 | +#' extension = c("R", "qmd", "csv", "png", "woff2") |
101 | 75 | #' ) |
102 | 76 | #' |
103 | 77 | #' classify_operational_file_type( |
|
0 commit comments