# The fscontext R Package `fscontext` provides a provenance-aware contextual reconstruction framework for file systems and related digital resource collections. The package creates reproducible observational snapshots of files, repository structures, and related operational resources, and supports their contextual abstraction, semantic stabilization, and reconstruction-oriented analysis. ## Installation ``` R # CRAN release install.packages("fscontext") # Latest development version pak::pak("dataobservatory-eu/fscontext") ``` ## Getting started The package includes five introductory vignettes that follow the typical `fscontext` workflow from filesystem observation to semantic stabilisation. - [Introduction to fscontext](https://fscontext.dataobservatory.eu/articles/intro.html) introduces filesystem observations, reproducible snapshots, and contextual reconstruction. - [Observing File Organisation](https://fscontext.dataobservatory.eu/articles/file_organisation.html) demonstrates how repeated filesystem observations can reconstruct ordinary human curation activities such as organising imported photographs into contextual collections. - [Working with Record Sets](https://fscontext.dataobservatory.eu/articles/recordset_df.html) demonstrates how observational data can be transformed into provenance-aware `recordset_df` objects inspired by the Records in Contexts (RiC) conceptual model. - [Prelabelled values and semantic stabilisation](https://fscontext.dataobservatory.eu/articles/prelabelled.html) introduces lightweight semantic enrichment, rulebooks, and human-in-the-loop refinement workflows. - [Organising Evidence with Structural Aggregations](https://fscontext.dataobservatory.eu/articles/structural_aggregations.html) demonstrates how structural aggregation metadata can identify potentially informative objects and candidate Record Sets across folders, ZIP archives, and WACZ packages. Together these vignettes introduce the observational, contextual, semantic, and analytical layers of the package. ## Context before semantics Many digital collections contain valuable contextual information but little documentation explaining how files, datasets, reports, source code, inventories, or digital surrogates relate to one another. Examples include research projects spread across multiple repositories, digitised archival collections with evolving inventories, audiovisual production environments, long-running analytical projects, and shared drives that have accumulated over many years. Before semantic integration, archival description, provenance modelling, or knowledge graph construction can begin, it is often necessary to reconstruct the context in which digital resources were created and used. `fscontext` approaches filesystems as observational environments. A common example is importing photographs from a camera or smartphone. Initially the files arrive as an unordered collection. As people organise them into folders such as `house`, `garden`, or `delete`, they create contextual information through ordinary filesystem operations. By comparing reproducible snapshots taken before and after this organisation, `fscontext` can reconstruct these contextual changes as observable evidence without interpreting their meaning. Files, folders, timestamps, repository structures, and other digital traces are treated as evidence from which contextual structures can be reconstructed. ``` R Filesystem observations ↓ Snapshots ↓ Contextual changes ↓ Snapshots ↓ Contextual reconstruction ↓ Record Sets ↓ Semantic stabilisation ↓ Knowledge systems ``` Rather than replacing archival description or provenance models, `fscontext` focuses on the earlier task of contextual reconstruction. The package is inspired by the archival conceptual model [Records in Contexts](https://www.ica.org/ica-network/expert-groups/egad/records-in-contexts-ric/) (RiC), developed by the *International Council on Archives*. Rather than implementing `RiC-CM` or `RiC-O` directly, `fscontext` focuses on the earlier task of contextual reconstruction: deriving contextual relationships and candidate `Record Sets` from filesystem observations, repository structures, inventories, and other digital traces. For more information, see: - [RiC-CM 1.0](https://www.ica.org/ica-network/expert-groups/egad/records-in-contexts-conceptual-model/) (Records in Contexts Conceptual Model) - [RiC-O 1.1](https://www.ica.org/standards/RiC/RiC-O_1-1.html) (Records in Contexts Ontology) ## A reproducible example The package includes two example filesystem snapshots derived from the companion repository `fscontextdemo`. The demonstration repository is available at: It contains a small but realistic digital work environment including source code, datasets, generated artefacts, documentation, tests, package metadata, semantic enrichment examples. The snapshots, `fscontextdemo_snapshot_01` and `fscontextdemo_snapshot_02`, capture the repository at different points in time, allowing reconstruction and longitudinal analysis workflows to be demonstrated reproducibly. ``` r library(fscontext) data("fscontextdemo_snapshot_02") fscontextdemo_snapshot_02 |> subset( select = c(storage_id, rel_path, filename, quick_sig) ) |> head() #> storage_id rel_path #> 1 fscontextdemo .github/.gitignore #> 2 fscontextdemo .github/workflows/pkgdown.yaml #> 3 fscontextdemo .gitignore #> 4 fscontextdemo .Rbuildignore #> 5 fscontextdemo data/fscontextdemo_snapshot_01.rda #> 6 fscontextdemo data/fsdemo_country_data.rda #> filename quick_sig #> 1 .gitignore db6ad734 #> 2 pkgdown.yaml 5eb4aaba_6cbfbdf4 #> 3 .gitignore e73cf12f #> 4 .Rbuildignore 09ab8617 #> 5 fscontextdemo_snapshot_01.rda 03dd3533_36abd309_cb1736f4 #> 6 fsdemo_country_data.rda f7e65210 ``` The snapshot records observed filesystem resources together with contextual information such as relative paths, timestamps, extensions, and storage identifiers. Contextual identifiers can then be added: ``` r data("fscontextdemo_snapshot_02") snapshot <- add_snapshot_context(fscontextdemo_snapshot_02) snapshot |> subset( select = c(storage_path_id, observation_id, rel_path) ) |> head() #> storage_path_id #> 1 fscontextdemo::.github/.gitignore #> 2 fscontextdemo::.github/workflows/pkgdown.yaml #> 3 fscontextdemo::.gitignore #> 4 fscontextdemo::.Rbuildignore #> 5 fscontextdemo::data/fscontextdemo_snapshot_01.rda #> 6 fscontextdemo::data/fsdemo_country_data.rda #> observation_id #> 1 fscontextdemo::.github/.gitignore::20260525-174640 #> 2 fscontextdemo::.github/workflows/pkgdown.yaml::20260525-174640 #> 3 fscontextdemo::.gitignore::20260525-174640 #> 4 fscontextdemo::.Rbuildignore::20260525-174640 #> 5 fscontextdemo::data/fscontextdemo_snapshot_01.rda::20260525-174640 #> 6 fscontextdemo::data/fsdemo_country_data.rda::20260525-174640 #> rel_path #> 1 .github/.gitignore #> 2 .github/workflows/pkgdown.yaml #> 3 .gitignore #> 4 .Rbuildignore #> 5 data/fscontextdemo_snapshot_01.rda #> 6 data/fsdemo_country_data.rda ``` The examples above demonstrate only the observational layer. Subsequent workflows can derive contextual Record Sets, compare repeated observations over time, identify duplicate resources, analyse activity patterns, and support semantic stabilisation. See the package vignettes for complete end-to-end examples. ## Core concepts The package separates three complementary analytical layers: | Layer | Purpose | |----|----| | Observation | Observe filesystems and related digital environments as reproducible snapshots. | | Context | Derive contextual identifiers, structural aggregations, and candidate Record Sets from observations. | | Record Sets | Create lightweight documentary objects using recordset_df, inspired by RiC. | | Semantic stabilisation | Support progressive semantic enrichment through prelabelled values, rulebooks, and human review. | | Analysis | Compare snapshots, detect duplicates, reconstruct activity, and analyse evolving digital work environments. | In RiC-inspired terms, filesystem observations represent observed digital resources and their associated instantiations at a particular point in time. These observations may later be aggregated into contextual `Record Sets` while preserving the distinction between the observed resources themselves and the contextual structures derived from them. The framework intentionally separates observation, contextual organisation, semantic stabilisation, and domain-specific interpretation. This allows the same observational evidence to support different analytical perspectives—including archival description, business process reconstruction, software development, digital forensics, historical research, and other forms of contextual analysis—without conflating the evidence with its interpretation. ## What this package does not do `fscontext` does not attempt to replace archival description, provenance ontologies, or knowledge graph platforms. Instead, it provides a reproducible observational and contextual layer that can support those systems by making digital working environments easier to understand, review, and reconstruct. ## Notes - Large scans may require substantial time on slower or networked storage systems. - Some files may be inaccessible due to permissions or synchronization state. - Observational snapshots are intended for reproducible local or institutional analysis workflows. - Contextual and analytical layers may evolve independently from the original observational corpus. # Package index ## Observation Observe digital resources and create reproducible filesystem snapshots. - [`scan_storage()`](https://fscontext.dataobservatory.eu/reference/scan_storage.md) : Observe a filesystem and construct a reproducible snapshot - [`snapshot_storage()`](https://fscontext.dataobservatory.eu/reference/snapshot_storage.md) : Create and persist an observational snapshot of a filesystem - [`save_scan()`](https://fscontext.dataobservatory.eu/reference/save_scan.md) : Persist an observational snapshot to disk - [`read_snapshot()`](https://fscontext.dataobservatory.eu/reference/read_snapshot.md) : Read and combine observational filesystem snapshots - [`subset_snapshot()`](https://fscontext.dataobservatory.eu/reference/subset_snapshot.md) : Subset observational filesystem Instantiations - [`observe_universe()`](https://fscontext.dataobservatory.eu/reference/observe_universe.md) : Construct a longitudinal observational universe - [`observe_wacz()`](https://fscontext.dataobservatory.eu/reference/observe_wacz.md) : Observe a WACZ web archive - [`quick_signature()`](https://fscontext.dataobservatory.eu/reference/quick_signature.md) : Compute a fast operational signature for a file - [`quick_signature_text()`](https://fscontext.dataobservatory.eu/reference/quick_signature_text.md) : Compute a fast operational signature for text ## Contextualisation Construct contextual groupings and enrich observations with structural context. - [`context_roots()`](https://fscontext.dataobservatory.eu/reference/context_roots.md) : Extract normalized contextual roots - [`coverage_roots()`](https://fscontext.dataobservatory.eu/reference/coverage_roots.md) : Evaluate contextual root coverage - [`derive_record_set()`](https://fscontext.dataobservatory.eu/reference/derive_record_set.md) : Derive contextual Record Set membership - [`invert_contextual_grouping()`](https://fscontext.dataobservatory.eu/reference/invert_contextual_grouping.md) : Invert contextual grouping mappings - [`add_snapshot_context()`](https://fscontext.dataobservatory.eu/reference/add_snapshot_context.md) : Add contextual identifiers to snapshot observations - [`add_structural_groups()`](https://fscontext.dataobservatory.eu/reference/add_structural_groups.md) : Attach structural grouping heuristics to snapshot observations - [`construct_structural_paths()`](https://fscontext.dataobservatory.eu/reference/construct_structural_paths.md) : Construct recursive contextual structural paths ## Analysis Analyse observations before semantic interpretation. - [`summarise_duplicates()`](https://fscontext.dataobservatory.eu/reference/summarise_duplicates.md) [`summarize_duplicates()`](https://fscontext.dataobservatory.eu/reference/summarise_duplicates.md) : Summarise repeated and divergent filesystem observations - [`summarise_observed_activity()`](https://fscontext.dataobservatory.eu/reference/summarise_observed_activity.md) [`summarize_observed_activity()`](https://fscontext.dataobservatory.eu/reference/summarise_observed_activity.md) : Summarise observed activity from filesystem observations - [`detect_generated_artifacts()`](https://fscontext.dataobservatory.eu/reference/detect_generated_artifacts.md) : Detect operationally generated or low-priority artifacts - [`exclude_operational_noise()`](https://fscontext.dataobservatory.eu/reference/exclude_operational_noise.md) : Exclude operational noise from analytical workflows - [`classify_operational_file_type()`](https://fscontext.dataobservatory.eu/reference/classify_operational_file_type.md) : Classify operational file types - [`derive_structural_groups()`](https://fscontext.dataobservatory.eu/reference/derive_structural_groups.md) : Derive structural aggregation metadata from relative paths ## Record Sets Create contextual Record Sets and semantically enriched recordset_df objects. - [`snapshot_to_reconstruction_context()`](https://fscontext.dataobservatory.eu/reference/snapshot_to_reconstruction_context.md) : Reconstruct a contextual observational Record Set from filesystem snapshots - [`snapshot_to_recordset_df()`](https://fscontext.dataobservatory.eu/reference/snapshot_to_recordset_df.md) : Create a contextual Record Set dataset - [`wacz_to_recordset_df()`](https://fscontext.dataobservatory.eu/reference/wacz_to_recordset_df.md) : Create a Record Set dataset from a WACZ observation - [`recordset_df()`](https://fscontext.dataobservatory.eu/reference/recordset_df.md) : Create a semantically annotated Record Set ## Semantic Stabilisation Prepare observations for human review and semantic enrichment. - [`prelabel()`](https://fscontext.dataobservatory.eu/reference/prelabel.md) : Create a prelabelled vector - [`is.prelabelled()`](https://fscontext.dataobservatory.eu/reference/is.prelabelled.md) : Test if a vector is prelabelled - [`as_character()`](https://fscontext.dataobservatory.eu/reference/as_character.md) : Semantic character coercion - [`as_value_key()`](https://fscontext.dataobservatory.eu/reference/as_value_key.md) : Standardize contextual semantic mappings - [`invert_value_key()`](https://fscontext.dataobservatory.eu/reference/invert_value_key.md) : Invert contextual semantic mappings - [`refine()`](https://fscontext.dataobservatory.eu/reference/refine.md) : Refine semantic assertions through contextual matching - [`refine_by_rulebook()`](https://fscontext.dataobservatory.eu/reference/refine_by_rulebook.md) : Iteratively refine semantic assertions using a rulebook - [`compile_rulebook()`](https://fscontext.dataobservatory.eu/reference/compile_rulebook.md) : Compile a semantic refinement rulebook - [`coverage_rules_path()`](https://fscontext.dataobservatory.eu/reference/coverage_rules_path.md) : Evaluate contextual rule coverage for structural paths ## Example Data Reproducible snapshots used throughout the documentation. - [`fscontextdemo_snapshot_01`](https://fscontext.dataobservatory.eu/reference/fscontextdemo_snapshot_01.md) : Example filesystem snapshot 01 - [`fscontextdemo_snapshot_02`](https://fscontext.dataobservatory.eu/reference/fscontextdemo_snapshot_02.md) : Second example filesystem snapshot # Articles ### Getting Started - [Introduction to fscontext](https://fscontext.dataobservatory.eu/articles/intro.md): - [Observing File Organisation](https://fscontext.dataobservatory.eu/articles/file_organisation.md): ### Contextual Reconstruction - [Working with Record Sets](https://fscontext.dataobservatory.eu/articles/recordset_df.md): - [From Structural Aggregations to Record Sets](https://fscontext.dataobservatory.eu/articles/structural_aggregations.md): ### Semantic Stabilisation - [Handling Semantic Ambiguity with prelabelled Vectors](https://fscontext.dataobservatory.eu/articles/prelabelled.md):