Summarise observed activity from filesystem observations — summarise_observed

summarise_observed_activity() summarises observed file-level modification evidence by time period and structural grouping.

The function is intended as a temporal contextualisation step. It does not infer archival Activities, Events, Record Sets, or provenance relations. Instead, it produces candidate activity summaries that may support later human review, semantic stabilisation, or RiC-aligned modelling.

Usage

summarise_observed_activity(
  df,
  extensions = c("r", "bak"),
  path_col = "rel_path",
  time_unit = c("week", "month", "day", "year"),
  max_files = 20
)

summarize_observed_activity(
  df,
  extensions = c("r", "bak"),
  path_col = "rel_path",
  time_unit = c("week", "month", "day", "year"),
  max_files = 20
)

Arguments

df

A data.frame representing filesystem observations. The data must contain:

rel_path;
filename;
mtime;
extension.

If present, git_tracked is used to count untracked files.

extensions

Character vector of file extensions to include, without leading dots. Matching is case-insensitive.

path_col

Character scalar. Name of the column containing paths used to derive structural groupings. Defaults to "rel_path".

time_unit

Character scalar. One of "week", "month", "day", or "year".

max_files

Integer. Maximum number of file names displayed in each summary row.

Value

A data.frame with one row per period and group_path combination.

The returned columns include:

period: Time bucket identifier.
group_path: Structural grouping key derived from path_col.
start: Earliest observed modification date in the group.
end: Latest observed modification date in the group.
file_names: Pipe-separated sample of observed file names.
n_files: Number of file observations in the group.
n_unique_files: Number of distinct paths in the group.
untracked: Number of observations not tracked by Git, when git_tracked is available; otherwise NA_integer_.

Details

Aggregates filesystem observations into reproducible temporal summaries grouped by structural path context.

The function derives:

period, a time bucket derived from file modification times (mtime);
group_path, a structural grouping key derived from the selected path column.

It then summarises observations within each period x group_path combination.

Modification times are treated as observational evidence of change. They are not interpreted as complete editing histories or confirmed archival events.

Structural grouping is deterministic and based on path structure. It is intended for aggregation, review, and reporting, not for file identity. Use rel_path for file-level identity.

Typical uses include:

identifying temporal clusters of filesystem activity;
reviewing candidate Activities before semantic stabilisation;
comparing activity across structural contexts;
supporting archival recontextualisation workflows;
preparing analytical or audit summaries.

Files under .Trash are excluded.

Examples

data("fscontextdemo_snapshot_02")

summarise_observed_activity(
  fscontextdemo_snapshot_02,
  time_unit = "month"
)
#> # A tibble: 8 × 8
#>   period  group_path     start      end        file_names n_files n_unique_files
#>   <chr>   <chr>          <date>     <date>     <chr>        <int>          <int>
#> 1 2026-05 R/data-fsdemo… 2026-05-25 2026-05-25 data-fsde…       1              1
#> 2 2026-05 R/fscontextde… 2026-05-25 2026-05-25 fscontext…       1              1
#> 3 2026-05 R/hello_world… 2026-05-25 2026-05-25 hello_wor…       1              1
#> 4 2026-05 R/label_count… 2026-05-25 2026-05-25 label_cou…       1              1
#> 5 2026-05 data-raw/crea… 2026-05-25 2026-05-25 create_fs…       1              1
#> 6 2026-05 data-raw/pack… 2026-05-25 2026-05-25 package_i…       1              1
#> 7 2026-05 tests/testthat 2026-05-25 2026-05-25 test-hell…       2              2
#> 8 2026-05 tests/testtha… 2026-05-25 2026-05-25 testthat.R       1              1
#> # ℹ 1 more variable: untracked <int>