
<!-- README.md is generated from README.Rmd. Please edit that file -->

# The fscontext R Package <a href='https://fscontext.dataobservatory.eu/'><img src="man/figures/logo.png" align="right"/></a>

<!-- badges: start -->

[![rhub](https://github.com/dataobservatory-eu/fscontext/actions/workflows/rhub.yaml/badge.svg)](https://github.com/dataobservatory-eu/fscontext/actions/workflows/rhub.yaml)
[![lifecycle](https://lifecycle.r-lib.org/articles/figures/lifecycle-experimental.svg)](https://lifecycle.r-lib.org/articles/stages.html#experimental)
[![Project Status:
WIP](https://www.repostatus.org/badges/latest/wip.svg)](https://www.repostatus.org/#wip)
[![devel-version](https://img.shields.io/badge/devel%20version-0.2.1-blue.svg)](https://github.com/dataobservatory-eu/fscontext/tree/devel)
[![dataobservatory](https://img.shields.io/badge/ecosystem-dataobservatory.eu-3EA135.svg)](https://dataobservatory.eu/)
[![codecov](https://codecov.io/gh/dataobservatory-eu/fscontext/branch/main/graph/badge.svg)](https://app.codecov.io/gh/dataobservatory-eu/fscontext)

<!-- badges: end -->

`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

    # 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.

    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:
<https://github.com/dataobservatory-eu/fscontextdemo>

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.

<!-- -->

<!-- -->
