Derive structural aggregation metadata from relative paths — derive_structural

Derives lightweight structural aggregation metadata from observed relative filesystem paths.

The function identifies recurring structural patterns in directory hierarchies and creates candidate aggregations that can support exploratory analysis, navigation, contextual reconstruction, and later semantic interpretation.

The resulting groupings are derived solely from path structure. They are analytical projections rather than authoritative Record Sets, provenance assertions, or documentary relationships.

Usage

derive_structural_groups(rel_path, profile = "folder-depth-2")

Arguments

rel_path

Character vector of relative filesystem paths.

profile

Character scalar specifying the structural aggregation strategy. Available profiles are:

"folder-depth-1": Group by the first directory level.
"folder-depth-2": Group by the first two directory levels (default).
"folder-depth-3": Group by the first three directory levels.
"folder-depth-4": Group by the first four directory levels.
"wacz": Use the first path component as the structural group and the second component as the structural subdivision, matching the standard organisation of WACZ archives.

Value

A data.frame with two columns:

structural_group: Candidate structural aggregation derived from the selected path profile.
component: Immediate structural subdivision within the aggregation, when present.

Details

Structural aggregation metadata provides a lightweight abstraction of observed directory organisation. It can increase the informativeness of filesystem observations by exposing recurring organisational patterns without asserting semantic meaning.

Within the fscontext workflow:

filesystem observations provide evidence about observed resources;
relative paths provide structural organisation;
structural aggregations expose candidate groups that may later support contextual reconstruction, Record Set construction, semantic stabilisation, or other downstream analyses.

Future versions may introduce additional aggregation profiles based on repository structure, provenance, temporal patterns, or other observational evidence.

Examples

rel_path <- c(
  "_packages/demo/R/file.R",
  "_packages/demo/tests/testthat/test-file.R",
  "_packages/demo/data/input.csv"
)

derive_structural_groups(rel_path)
#> # A tibble: 3 × 2
#>   structural_group component
#>   <chr>            <chr>    
#> 1 _packages/demo   R        
#> 2 _packages/demo   tests    
#> 3 _packages/demo   data     

derive_structural_groups(
  rel_path,
  profile = "folder-depth-1"
)
#> # A tibble: 3 × 2
#>   structural_group component
#>   <chr>            <chr>    
#> 1 _packages        demo     
#> 2 _packages        demo     
#> 3 _packages        demo     

derive_structural_groups(
  c(
    "archive/data.warc.gz",
    "indexes/index.cdx",
    "pages/pages.jsonl"
  ),
  profile = "wacz"
)
#> # A tibble: 3 × 2
#>   structural_group component   
#>   <chr>            <chr>       
#> 1 archive          data.warc.gz
#> 2 indexes          index.cdx   
#> 3 pages            pages.jsonl