Package 'pressR'

Description

Visualizes a pr_layout showing active sensor positions and colored region masks (if any).

Usage

## S3 method for class 'pr_layout'
plot(x, show_regions = TRUE, show_ids = FALSE, ...)

Arguments

Value

A ggplot2 object.

Examples

plot(pr_layout_saddle("horse"))

Description

Default plot method for pr_trial — shows the maximum pressure picture (MPP) as a heatmap.

Usage

## S3 method for class 'pr_trial'
plot(x, ...)

Arguments

Value

A ggplot2 object.

Description

Checks that a cohort holds exactly the expected number of units (trials or rows) and, optionally, of distinct subjects. Aborts with a message naming the expectation, the actual count, and the shortfall or surplus.

Usage

pr_assert_cohort(
  x,
  n_units = NULL,
  n_subjects = NULL,
  unit_col = NULL,
  subject_col = NULL,
  label = NULL
)

Arguments

Details

Use it as a tripwire around every step that can silently drop data — reading a directory, filtering, joining. A guard that has never fired proves nothing, so give it the real numbers from your design.

Value

Invisibly returns x, so the assertion can sit in a pipeline. Aborts with condition class pr_cohort_assert_failed on mismatch.

See Also

Other cohort functions: pr_dataset_filter(), pr_design_table(), pr_validate_dataset()

Examples

design <- data.frame(
  ID = c("ID001", "ID001", "ID002"),
  Mode = c("MS", "MH", "MS")
)
pr_assert_cohort(design, n_units = 3, n_subjects = 2, subject_col = "ID")

# A wrong expectation fails loudly:
try(pr_assert_cohort(design, n_units = 431, label = "all recordings"))

Description

Runs pr_frame_metrics() over every trial in a dataset and reduces each frame table to a single row: the nine summary statistics a cohort analysis reports per recording, plus the trial's metadata.

Usage

pr_batch_frame_summary(
  dataset,
  threshold = 0,
  meta_fields = NULL,
  .progress = FALSE
)

Arguments

Details

Columns, in order: the requested metadata fields, then

• mean_kPa_avg — mean over frames of the whole-grid frame mean.

• mean_kPa_sd — standard deviation over frames of that same quantity, i.e. how much overall load varied during the recording (NA for a single-frame trial).

• peak_kPa_max — the largest single-sensor reading anywhere in the recording. On a saturating device this pins to the hardware ceiling.

• peak_kPa_avg — mean over frames of the frame maximum. Together with mean_kPa_avg this gives the concentration index peak_kPa_avg / mean_kPa_avg (see pr_calc_pci()).

• total_kPa_avg — mean over frames of the frame sum. Exactly mean_kPa_avg * n_sensors; a sum of pressures, never a force.

• loaded_avg — mean over frames of the loaded cell count.

• cop_row_mean, cop_col_mean — mean over frames of the centre of pressure, in grid index units.

• n_frames — frames in the recording, after any the reader dropped.

These names and definitions are the cohort contract, chosen so the result can be compared column-for-column against a study's own summary table. Note that mean_kPa_avg is the whole-grid mean including unloaded cells (see pr_calc_mean_pressure_grid()), which is a different quantity from pr_calc_mean_pressure().

Value

A tibble::tibble with one row per trial.

Memory

The frame tables are built and discarded one at a time, so peak memory is one recording's frames, not the cohort's. That matters: 431 recordings of 5.5 M frames total would need several gigabytes if every frame table were materialised first, to produce nine numbers each.

See Also

pr_frame_metrics() for the per-frame table this summarises, pr_design_table() for the metadata side alone.

Other sensor aggregation functions: pr_profile_matrix(), pr_sensor_map()

Examples

ds <- pr_dataset(list(
  pr_example_trial("saddle_horse", seed = 1),
  pr_example_trial("saddle_horse", seed = 2)
))
fs <- pr_batch_frame_summary(ds, meta_fields = character(0))
names(fs)
round(fs$mean_kPa_avg, 3)

# total_kPa_avg is mean_kPa_avg scaled by the sensor count:
n_sensors <- ds$trials[[1]]$layout$n_sensors
all.equal(fs$total_kPa_avg, fs$mean_kPa_avg * n_sensors)

Description

Runs pr_summary() on each trial in a dataset and row-binds the results, prepending trial metadata columns.

Usage

pr_batch_summary(dataset)

Arguments

Value

A tibble::tibble with one row per trial.

Examples

ds <- pr_dataset(list(
  pr_example_trial("insole", seed = 1),
  pr_example_trial("insole", seed = 2)
))
pr_batch_summary(ds)

Description

Number of sensors above threshold times the per-sensor area (cm^2).

Usage

pr_calc_contact_area(trial, threshold = 0)

Arguments

Value

Numeric vector of contact area (cm^2) per frame.

Description

Duration for which at least one sensor exceeds threshold.

Usage

pr_calc_contact_time(trial, threshold = 0)

Arguments

Value

Numeric scalar (s).

Description

Computes the pressure-weighted centroid of active sensors for each frame. Frames with no loaded sensors return NA for x and y.

Usage

pr_calc_cop(trial, threshold = 0)

Arguments

Value

A pr_cop object containing x (mm), y (mm), time (s), and derived metrics.

Examples

cop <- pr_calc_cop(pr_example_trial("saddle_horse"))
print(cop)

Description

COP Excursion (Anterior-Posterior and Medial-Lateral Range)

Usage

pr_calc_cop_excursion(trial, threshold = 0)

Arguments

Value

Named numeric vector with ap (y-range, mm) and ml (x-range, mm).

Description

Pressure-weighted centroid of each frame expressed in grid indices: a cop_row of 1 is the first sensor row, a cop_col of 16 the sixteenth sensor column. Row and col are read from the layout's coordinate table positionally, so the result stays correct under any device channel permutation applied by the reader.

Usage

pr_calc_cop_grid(trial, threshold = 0, eps = 1e-12)

Arguments

Details

pr_calc_cop() returns the same centroid in millimetres and gives NA for frames with no load. This function is the index-unit counterpart used when a device's physical sensor pitch was never published, so millimetre coordinates would be fabricated. Instead of NA, an unloaded frame gets a centroid of approximately 0 for both axes: eps is added to the weight sum, so the quotient is 0 / eps rather than 0 / 0. That keeps the output a complete, non-NA time series, and cop_row == 0 is unambiguous because a real centroid is always at least 1.

Note also that the whole-grid metrics here differ from pr_calc_mean_pressure(), which is loaded-cells-only by definition.

Value

A tibble::tibble with one row per frame and columns frame (integer), time_s, cop_row, cop_col (grid index units).

See Also

Other whole-grid frame metrics: pr_calc_loaded_count(), pr_calc_mean_pressure_grid(), pr_calc_pci(), pr_calc_total_pressure(), pr_frame_metrics(), pr_ref_pci()

Examples

trial <- pr_example_trial("saddle_horse")
cop <- pr_calc_cop_grid(trial)
range(cop$cop_row)

Description

Computes one centre-of-pressure trajectory for each region mask, weighted only by that region's sensors. Returns a list of pr_cop objects, so the existing trajectory vocabulary — path length, mean and maximum velocity, the x/y ranges pr_calc_cop_excursion() reports, and the 95% ellipse sway area — is available per region with no further work.

Usage

pr_calc_cop_masked(trial, masks = NULL, threshold = 0, units = c("grid", "mm"))

Arguments

Details

A whole-mat COP is a single point that can sit in an unloaded gap between two loaded zones, and it moves whenever load shifts between zones. A per-region COP cannot: it stays inside its own region and reports how load migrated within it, which is what separates a saddle that rocks fore-and-aft from one that slides sideways.

Frames in which a region carries no load at all get NA for both axes, exactly as pr_calc_cop() does for the whole mat. pr_cop() excludes those frames from the trajectory metrics, so a region that is loaded only intermittently still reports a meaningful path length — though one measured across the gaps, not through them.

Value

A named list of pr_cop objects, one per mask, in the order the masks were given.

Units

units = "grid" (the default) returns grid index units: x is the fractional sensor column, y the fractional sensor row, both 1-based, in the convention of pr_calc_cop_grid(). This is always available.

units = "mm" returns the layout's physical x_mm / y_mm coordinates, as pr_calc_cop() does. It is refused for a layout whose coordinates are grid indices because no sensor pitch was ever published (see the Missing physical scale section of pr_layout_from_index_map()) — millimetres would be fabricated, and a path length in fabricated millimetres is worse than none.

Note that a pr_cop object labels its fields mm regardless; under units = "grid" they are grid indices, and the derived path length and velocity are in index units and index units per second.

See Also

pr_calc_cop() and pr_calc_cop_grid() for the whole mat, pr_calc_cop_excursion() for the range summary.

Other regional symmetry functions: pr_calc_regional_map(), pr_calc_symmetry_map(), pr_mask_mirror_balance(), pr_mask_rowbands(), pr_symmetry_sensitivity()

Examples

trial <- pr_example_trial("saddle_horse")
cops <- pr_calc_cop_masked(trial)
names(cops)

# Each region's COP stays inside its own rows:
round(vapply(cops, function(c) mean(c$y, na.rm = TRUE), numeric(1)), 2)

# The full pr_cop vocabulary works unchanged:
round(vapply(cops, function(c) c$path_length, numeric(1)), 3)

# This layout has a real sensor pitch, so millimetres are honest:
round(pr_calc_cop_masked(trial, units = "mm")$cranial_left$range_x, 1)

Description

Total COP Path Length

Usage

pr_calc_cop_path(trial, threshold = 0)

Arguments

Value

Numeric scalar (mm).

Description

The strongest frequency of pr_calc_spectrum() inside a search band — on a saddle recording, the stride frequency.

Usage

pr_calc_dominant_freq(
  trial,
  band = c(0.3, 5),
  signal = "total",
  window = "hann"
)

Arguments

Details

The default band of 0.3-5 Hz brackets equine stride rates from a slow walk to a fast canter while excluding both the baseline drift below it and sensor noise above it. Band edges are inclusive, and the search happens on the exact frequency axis documented in pr_calc_spectrum().

The result is the single largest bin, with no interpolation between bins, so its resolution is fs / n_frames — 0.058 Hz for a 869-frame recording at 50 Hz. A recording with no oscillation still returns its largest in-band bin; read peak_power before trusting the frequency, and compare against pr_calc_stride_cycles(), which measures the same rhythm in the time domain and disagrees when there is nothing periodic to find.

Value

A one-row tibble::tibble with columns stride_freq_Hz and peak_power. Both are NA (with a warning) when the band contains no frequency bin.

See Also

pr_calc_spectrum() for the full spectrum.

Other temporal structure functions: pr_calc_phase_map(), pr_calc_spectrum(), pr_calc_stride_cycles(), pr_cop_shape()

Examples

trial <- pr_example_trial("saddle_horse")
pr_calc_dominant_freq(trial)

# A stride frequency and a mean stride duration are reciprocals:
f <- pr_calc_dominant_freq(trial)$stride_freq_Hz
cycles <- pr_calc_stride_cycles(trial)
round(c(from_spectrum = 1 / f, from_cycles = mean(cycles$duration_s)), 2)

Description

Force in Newtons equals sum(pressure * sensor_area). With pressure in kPa and area in cm^2, force[N] = sum(p_kPa * a_cm2) * 0.1.

Usage

pr_calc_force(trial)

Arguments

Value

Numeric vector of length n_frames.

Description

Identifies heel-strike and toe-off events from the total force curve of in-shoe or platform pressure data, segmenting the trial into individual stance phases.

Usage

pr_calc_gait_cycles(
  trial,
  force_threshold = 20,
  min_stance_ms = 200,
  min_swing_ms = 100
)

Arguments

Value

A tibble::tibble with one row per detected cycle.

Examples

cycles <- pr_calc_gait_cycles(pr_example_trial("insole"))
cycles

Description

How sharply pressure changes from one sensor to its neighbours. The per-sensor map produced by pr_sensor_map() is arranged back onto the device grid, differenced in both directions, and returned as one gradient magnitude per sensor.

Usage

pr_calc_gradient(
  trial,
  statistic = "mean",
  method = "central",
  edges = c("na", "zero"),
  threshold = 0
)

Arguments

Details

For a grid M of per-sensor values, method = "central" computes

$g_{r,c} = \sqrt{\left(\frac{M_{r+1,c}-M_{r-1,c}}{2}\right)^2 + \left(\frac{M_{r,c+1}-M_{r,c-1}}{2}\right)^2}$

and method = "forward" uses the one-sided differences M[r+1, c] - M[r, c] and M[r, c+1] - M[r, c] instead. Central differences are symmetric and less noisy; forward differences reach one cell further into the edge, which matters on a small grid.

The result is in the trial's pressure unit per sensor spacing — kPa per cell step, not kPa/mm. Converting to kPa/mm needs a published cell pitch, and the saddle mat has none (see the Missing physical scale section of pr_layout_from_index_map()), so no distance scaling is done anywhere in this function. Gradients are therefore comparable across recordings on the same device and not across devices with different pitches.

Value

A tibble::tibble with one row per sensor, in the same column-major grid order as pr_sensor_map(), and columns sensor (integer), row, col (integer grid indices) and gradient (numeric).

The edge ring

A central difference needs a neighbour on both sides, so it is undefined on the outermost row and column. The two edges settings differ only there, and the interior is bit-for-bit identical either way:

• edges = "na" (default) leaves the ring NA. This is the honest answer: no gradient was computed for those cells.

• edges = "zero" fills the ring with 0. This reproduces the cohort analysis, which wrote central differences for rows and columns 2:(n-1) into a zero-initialised matrix and never revisited the border. On a 16x16 mat that makes 60 of 256 cells — nearly a quarter — a structural zero rather than a measurement. Use it to reproduce published numbers, but never average, rank or threshold over the whole grid with it: the mean gradient is biased down by a factor of roughly 196/256, and "the lowest-gradient cells" will be the border, every time. edges = "na" with na.rm = TRUE gives the interior mean the zero-filled version was probably meant to be.

Cells the layout marks inactive are NA in the grid, so a gradient that would have had to read one comes back NA under either setting.

See Also

pr_sensor_map() for the map being differentiated.

Other sensor quality functions: pr_sensor_quality()

Examples

trial <- pr_example_trial("saddle_horse")
g <- pr_calc_gradient(trial)
g[which.max(g$gradient), ]

# The default leaves the border -- and the layout's inactive gullet
# cells -- missing ...
sum(is.na(g$gradient))
# ... while the cohort's zero-filled convention hides the border:
gz <- pr_calc_gradient(trial, edges = "zero")
sum(gz$gradient == 0, na.rm = TRUE)

# Same interior, different whole-grid mean:
c(interior = mean(g$gradient, na.rm = TRUE),
  filled = mean(gz$gradient, na.rm = TRUE))

Description

Integrates total force over time. Result is in N*s.

Usage

pr_calc_impulse(trial)

Arguments

Value

Numeric scalar.

Description

Number of sensors reading strictly above threshold in each frame.

Usage

pr_calc_loaded_count(trial, threshold = 0)

Arguments

Details

The count that pr_calc_mean_pressure() divides by, exposed on its own. pr_calc_loaded_rate() returns the same information as a fraction of the grid and pr_calc_contact_area() scales it by the cell area; this function keeps it as a plain cell count, which is the form the cohort summaries report because the device's cell area is unknown.

Value

Integer vector of length n_frames.

See Also

Other whole-grid frame metrics: pr_calc_cop_grid(), pr_calc_mean_pressure_grid(), pr_calc_pci(), pr_calc_total_pressure(), pr_frame_metrics(), pr_ref_pci()

Examples

trial <- pr_example_trial("saddle_horse")
loaded <- pr_calc_loaded_count(trial)
max(loaded) <= trial$layout$n_sensors

Description

Calculate Fraction of Loaded Sensors Per Frame

Usage

pr_calc_loaded_rate(trial, threshold = 0)

Arguments

Value

Numeric vector in ⁠[0, 1]⁠ of length n_frames.

Description

Mean of loaded sensors per frame (sensors at or below threshold are excluded).

Usage

pr_calc_mean_pressure(trial, threshold = 0)

Arguments

Value

Numeric vector of length n_frames.

Description

Mean pressure across the entire sensor grid for each frame: the frame sum divided by the number of sensors, with unloaded cells counted as zeros.

Usage

pr_calc_mean_pressure_grid(trial)

Arguments

Details

This is deliberately not the same quantity as pr_calc_mean_pressure(), which averages only the cells above threshold (loaded-cells-only, by definition) and is left untouched. On a saddle mat where a typical frame loads roughly 4% of the 256 cells, the loaded-cells-only mean is around 25 times the whole-grid mean, so the two are never interchangeable. Use this one when the mat itself is the region of interest and an unloaded cell is a real "no pressure here" measurement; use pr_calc_mean_pressure() when the sensor sheet is larger than the loaded object and only the contact patch is meaningful.

The denominator is trial$layout$n_sensors, i.e. the number of active sensors, which equals ncol(trial$pressure). Inactive grid cells are not measurements and never enter the average.

Value

Numeric vector of length n_frames, in the trial's pressure unit.

See Also

Other whole-grid frame metrics: pr_calc_cop_grid(), pr_calc_loaded_count(), pr_calc_pci(), pr_calc_total_pressure(), pr_frame_metrics(), pr_ref_pci()

Examples

trial <- pr_example_trial("saddle_horse")
grid_mean <- pr_calc_mean_pressure_grid(trial)
loaded_mean <- pr_calc_mean_pressure(trial)
# The whole-grid mean is the smaller of the two by construction:
all(grid_mean <= loaded_mean + 1e-9)

Description

Ratio of a recording's average frame peak to its average frame mean. A PCI of 1 would mean a perfectly uniform mat; the larger the value, the more of the load sits under a single hotspot.

Usage

pr_calc_pci(trial, denominator = c("grid", "loaded"), eps = 1e-12)

Arguments

Details

PCI = mean(peak_kPa) / mean(mean_kPa) — a ratio of two per-recording averages, not the average of a per-frame ratio; the two differ whenever load varies over time, and the cohort summaries use the former.

denominator selects which mean goes underneath:

• "grid" (default) uses pr_calc_mean_pressure_grid(), the whole-grid mean including unloaded cells. This is the cohort definition and the one whose interpretation bands pr_ref_pci() documents.

• "loaded" uses the loaded-cells-only mean of pr_calc_mean_pressure(), which is a different quantity — that function is loaded-cells-only by definition and is untouched here. Values come out roughly an order of magnitude smaller on a sparsely loaded mat, and pr_ref_pci() does not apply to them.

eps guards the denominator so a recording with no load at all returns 0 instead of NaN.

Value

A single numeric value (dimensionless ratio).

See Also

Other whole-grid frame metrics: pr_calc_cop_grid(), pr_calc_loaded_count(), pr_calc_mean_pressure_grid(), pr_calc_total_pressure(), pr_frame_metrics(), pr_ref_pci()

Examples

trial <- pr_example_trial("saddle_horse")
pr_calc_pci(trial)
# The loaded-cells-only denominator is larger, so the index is smaller:
pr_calc_pci(trial, denominator = "loaded") < pr_calc_pci(trial)

Description

Returns the maximum pressure across all active sensors for each frame.

Usage

pr_calc_peak_pressure(trial, threshold = 0)

Arguments

Value

Numeric vector of length n_frames.

Examples

trial <- pr_example_trial("insole")
pp <- pr_calc_peak_pressure(trial)
length(pp) == trial$n_frames

Description

Resamples the whole sensor map — all 256 cells on a saddle mat — onto percent-of-cycle: for each phase bin, the mean pressure every sensor carried while the stride was in that part of its cycle. This is the ensemble average an animation or a phase-by-phase heatmap series is drawn from.

Usage

pr_calc_phase_map(
  trial,
  cycles = NULL,
  n_bins = 10L,
  trim = 0.1,
  min_frames = 10L
)

Arguments

Details

Each cycle from pr_calc_stride_cycles() is stretched onto 0-100% of itself — frame i of a cycle spanning m frames sits at (i - 1) / (m - 1) * 100 percent — and its frames are dropped into n_bins equal-width bins, with 100% falling in the last bin. Every sensor is averaged within a bin, giving one map per bin per cycle, and those per-cycle maps are then averaged across cycles.

Averaging per cycle first, rather than pooling all frames, weights every stride equally. Pooling would let a long stride, which contributes more frames, dominate the ensemble; strides in a recording vary in length by a factor of three or more, so the difference is real.

trim is passed to mean() as it averages across cycles within a bin, so trim = 0.1 discards the highest and lowest 10% of cycles in each bin and each cell before averaging. That protects the ensemble from a single stride where the horse stumbled or the rider shifted, at the cost of ignoring genuine extremes. trim = 0 gives the plain mean.

Cycles shorter than min_frames frames are skipped: too few frames make the phase bins mostly empty, and an empty bin contributes nothing rather than a zero. A bin no cycle ever reached comes back NA.

Value

A tibble::tibble with n_bins * n_sensors rows, ordered by phase_bin then sensor, and columns phase_bin (integer, 1 to n_bins), sensor, row, col (integer, as in pr_sensor_map()) and mean_kPa. Zero rows, with a warning, when no cycle qualifies.

Agreement with the source study

The study's phase maps used the plain mean across cycles (trim = 0). On the reference recording ID052_K_K_KG00_MS, and on the same 14 cycles, this function at trim = 0 reproduces all 2,560 of its values with a correlation of 0.99998, a mean absolute difference of 0.007 kPa and a maximum of 0.12 kPa, on values ranging up to 6.9 kPa. Close, but not exact: the residual difference has not been traced to any documented step, so treat the two as equivalent in aggregate rather than interchangeable cell by cell. At the default trim = 0.1 the same comparison gives 0.011 kPa mean and 0.18 kPa maximum, the extra difference being the trimming itself.

See Also

pr_sensor_map() for the same map reduced over the whole recording instead of over the cycle.

Other temporal structure functions: pr_calc_dominant_freq(), pr_calc_spectrum(), pr_calc_stride_cycles(), pr_cop_shape()

Examples

trial <- pr_example_trial("saddle_horse")
pm <- pr_calc_phase_map(trial)
nrow(pm) == 10 * trial$n_sensors

# Where the load sits at the start of the cycle versus its middle:
first <- pm$mean_kPa[pm$phase_bin == 1]
mid <- pm$mean_kPa[pm$phase_bin == 5]
round(c(bin1 = max(first), bin5 = max(mid)), 2)

# Averaged over all bins, the phase map returns the recording's own
# per-sensor mean to within the trimming:
avg <- tapply(pm$mean_kPa, pm$sensor, mean)
round(stats::cor(as.numeric(avg), pr_sensor_map(trial, "mean")$value), 3)

Description

Integrates pressure over time for each sensor using the trapezoidal rule. Result is in kPa*s.

Usage

pr_calc_pti(trial)

Arguments

Value

Numeric vector of length n_sensors.

Description

Applies region masks to a trial and computes summary parameters independently for each region. Returns one row per region.

Usage

pr_calc_regional(
  trial,
  masks = NULL,
  parameters = c("mpp", "mvp", "max_force", "contact_area", "pti_mean"),
  threshold = 0
)

Arguments

Value

A tibble::tibble with one column region plus one column per requested parameter.

Examples

trial <- pr_example_trial("saddle_horse")
pr_calc_regional(trial)

Description

Summarises each region mask on the per-sensor map: every sensor is first reduced over its own frames, and the zone statistics are then taken across the sensors of the zone.

Usage

pr_calc_regional_map(
  trial,
  masks = NULL,
  statistic = c("mean", "max", "loaded"),
  threshold = 0
)

Arguments

Value

A tibble::tibble with one row per mask and columns zone, zone_mean_kPa, zone_peak_kPa, zone_loaded.

Operator order

This is the opposite order to pr_calc_regional(), and the two give different numbers on purpose.

• pr_calc_regional() reduces over sensors within a frame, then over frames. Its mpp is the largest single reading the zone ever produced, in any frame.

• pr_calc_regional_map() reduces over frames within a sensor, then over sensors. Its zone_peak_kPa is the largest time-averaged cell, which is smaller — often several-fold — because no cell holds its maximum for a whole recording.

Neither is more correct; they answer different questions. Use pr_calc_regional() to report what the worst moment looked like, and this function to report which cells carry load over the ride, which is the quantity a cohort-level zone table compares between horses.

Columns

Writing v for the per-sensor map and Z for a zone's sensors:

• zone_mean_kPa — mean(v[Z]), over all the zone's sensors, with never-loaded ones contributing zeros. The mat is the region of interest, so an unloaded cell is a real measurement (compare pr_calc_mean_pressure_grid()).

• zone_peak_kPa — max(v[Z]).

• zone_loaded — sum(v[Z] > 0), the number of the zone's sensors that ever carried load above threshold.

A zone with no sensors at all returns three zeros rather than NaN.

With statistic = "loaded" the map is a duty cycle in ⁠[0, 1]⁠, not a pressure, and the first two columns carry fractions; the column names are kept fixed so a cohort table has one schema.

See Also

pr_sensor_map() for the map being reduced, pr_calc_regional() for the frame-first counterpart.

Other regional symmetry functions: pr_calc_cop_masked(), pr_calc_symmetry_map(), pr_mask_mirror_balance(), pr_mask_rowbands(), pr_symmetry_sensitivity()

Examples

trial <- pr_example_trial("saddle_horse")
pr_calc_regional_map(trial)

# The sensor-first peak is never above the frame-first peak:
zm <- pr_calc_regional_map(trial)
zf <- pr_calc_regional(trial, parameters = "mpp")
all(zm$zone_peak_kPa <= zf$mpp + 1e-9)

# An explicit band split, rather than the layout's own regions:
pr_calc_regional_map(trial, pr_mask_rowbands(trial$layout, sides = FALSE))

Description

Computes the center of pressure progression during the stance phase of each gait cycle, resampled to percent of stance (0-100).

Usage

pr_calc_rollover(trial, cycles = NULL, n_points = 51L)

Arguments

Value

A tibble::tibble with columns cycle, percent_stance, cop_x_mm, cop_y_mm, cop_velocity.

Description

Identifies "bridging" — a saddle fit problem where the middle region is unloaded while cranial and caudal regions carry excessive pressure. Bridging is quantified as the ratio of middle-region pressure to the mean of cranial and caudal pressures.

Usage

pr_calc_saddle_bridge(trial, masks = NULL, bridge_threshold = 0.5)

Arguments

Value

A list with class pr_saddle_bridge:

• bridge_ratio: middle / mean(cranial, caudal) MVP ratio.

• is_bridged: logical.

• regional_pressures: tibble with MVP per region.

• recommendation: character.

Examples

pr_calc_saddle_bridge(pr_example_trial("saddle_horse"))

Description

Analyzes left/right pressure asymmetry over time to detect saddle slip or systematic asymmetric loading.

Usage

pr_calc_saddle_slip(trial, masks = NULL, slip_threshold = 15)

Arguments

Value

A list with class pr_saddle_slip.

Examples

pr_calc_saddle_slip(pr_example_trial("saddle_horse"))

Description

Finds sensors exceeding a clinical pressure threshold — relevant for pressure ulcer risk assessment in wheelchair seating.

Usage

pr_calc_seat_hotspot(trial, threshold = 4.7, duration_s = 0)

Arguments

Value

A tibble::tibble with columns sensor_id, row, col, x_mm, y_mm, max_pressure, mean_pressure, duration_above_s.

Examples

pr_calc_seat_hotspot(pr_example_trial("wheelchair"))

Description

Frequency content of a whole-mat time series: how much of the recording's variation sits at each frequency. On a saddle mat the stride shows up as a peak somewhere between 0.5 and 2 Hz.

Usage

pr_calc_spectrum(
  trial,
  signal = c("total", "mean", "peak"),
  window = c("hann", "none"),
  detrend = TRUE
)

Arguments

Details

The signal is taken from the pressure matrix directly:

• "total" — the frame sum, pr_calc_total_pressure().

• "mean" — the whole-grid frame mean, pr_calc_mean_pressure_grid(). This is "total" divided by the constant n_sensors, so its spectrum is the "total" spectrum scaled by 1 / n_sensors^2 and the peak sits at exactly the same frequency.

• "peak" — the frame maximum, which is not a scaled copy of the other two and saturates flat on a device that clips at its ceiling.

detrend = TRUE subtracts the mean before transforming, which removes the DC term that would otherwise dominate a signal sitting on a large constant offset. It does not remove a linear ramp. window = "hann" then tapers the ends, trading a little frequency resolution for far less leakage from the strong low-frequency components a drifting baseline produces; window = "none" leaves the segment rectangular.

Power is Mod(fft(x))^2 / n, kept for the non-negative frequencies only (n %/% 2 + 1 values, including DC and — for even n — Nyquist). It is a squared pressure quantity in the device's own unit, not a density: it is not divided by the frequency bin width, and it is not corrected for the window's power loss, so absolute values are comparable only between recordings of the same length analysed the same way.

Value

A tibble::tibble with n %/% 2 + 1 rows and columns freq_Hz (ascending, starting at 0) and power.

Frequency axis

The axis is built as (0:(n %/% 2)) * fs / n, which is the exact centre frequency of FFT bin k for both odd and even n.

The study this function reproduces built it as seq(0, fs / 2, length.out = length(power)) instead. For even n the two agree exactly. For odd n they do not: that sequence has spacing fs / (n - 1) rather than fs / n, and it places its last value at fs / 2, which for odd n is not an FFT bin at all — the highest real bin is at ((n - 1) / 2) * fs / n, just below Nyquist. On the 869-frame reference recording the error is a uniform stretch of n / (n - 1), about 0.12%: the study reports a stride at 0.7488 Hz where the exact axis puts it at 0.7480 Hz. power is unaffected — only the labels move. This function implements the exact axis.

See Also

pr_calc_dominant_freq() for the peak of this spectrum, pr_calc_stride_cycles() for the time-domain counterpart.

Other temporal structure functions: pr_calc_dominant_freq(), pr_calc_phase_map(), pr_calc_stride_cycles(), pr_cop_shape()

Examples

trial <- pr_example_trial("saddle_horse")
spec <- pr_calc_spectrum(trial)
nrow(spec) == trial$n_frames %/% 2 + 1

# The strongest non-DC component is the stride:
round(spec$freq_Hz[which.max(spec$power[-1]) + 1], 3)

# "mean" is "total" scaled by n_sensors, so power scales by its square:
m <- pr_calc_spectrum(trial, signal = "mean")
all.equal(m$power * trial$layout$n_sensors^2, spec$power)

Description

Peak-to-peak segmentation of a never-unloading recording. The frame-level signal is band-passed to isolate the stride oscillation from the baseline the rider's mass sets, and each interval between two successive peaks of that oscillation is one cycle.

Usage

pr_calc_stride_cycles(
  trial,
  signal = "total",
  lp_window = 11L,
  hp_window_s = 5,
  min_period_s = 0.3,
  height_quantile = 0.3,
  max_period_s = 3
)

Arguments

Details

This is the replacement for pr_calc_gait_cycles() on mats that stay loaded. That function pairs a threshold crossing up with the next crossing down; a saddle mat never crosses back down, so it returns a single "cycle" spanning the whole recording no matter how force_threshold is set. The problem is the segmentation model, not its tuning, so nothing about pr_calc_gait_cycles() is changed here.

The pipeline, in order:

1. Signal. signal selects the frame-level series exactly as in pr_calc_spectrum(). "total" and "mean" differ by the constant n_sensors, so they give identical segmentation; only peak_total changes scale.

2. Low pass. An lp_window-sample centred moving average. Frames at the two ends, where the window overhangs the recording, keep their raw value rather than becoming NA, so the first and last strides are still detectable.

3. High pass. Subtract a running median over hp_window_s seconds. The median steps over the stride peaks instead of being pulled up by them, so the residual keeps its amplitude while the baseline drift — the rider settling, the horse changing gait — is removed.

4. Peaks. Strict local maxima of the residual at or above stats::quantile(residual[residual > 0], height_quantile), thinned tallest-first so no two peaks sit closer than round(min_period_s * fs) samples.

5. Cycles. Every consecutive pair of peaks, keeping those whose duration lies in ⁠[min_period_s, max_period_s]⁠.

cycle numbers the peak pairs before the duration filter, so a gap in the sequence marks an interval that was rejected as too short or too long — information a renumbered column would hide.

peak_total is the band-passed amplitude at the cycle's opening peak, in the device's pressure unit. It is an excursion above the local baseline, not a raw frame total: on the reference recording the frame totals run 383-434 kPa while peak_total runs 2.5-13.8 kPa.

Value

A tibble::tibble with one row per accepted cycle and columns cycle (integer, gapped — see Details), start_idx, end_idx (integer frame indices of the bounding peaks), start_s, end_s, duration_s (seconds), peak_total (band-passed amplitude at start_idx) and stride_freq (1 / duration_s, Hz). Zero rows when fewer than two peaks survive.

Agreement with the source study

On the 869-frame reference recording ID052_K_K_KG00_MS, the defaults reproduce the study's own segmentation exactly: 14 cycles, identical cycle, start_idx, end_idx, duration_s, peak_total and stride_freq to machine precision. Rerun over the study's whole cohort, all 323 of its 50 Hz recordings match cycle for cycle — 137,761 cycles, no differences.

The remaining 108 recordings were sampled at 10 Hz, and there the two disagree. The study hard-coded its running-median width at 251 samples and its minimum peak separation at 15 samples, which are 5 s and 0.3 s only at 50 Hz; the parameters here are in seconds and scale with the trial's own sampling rate. Passing hp_window_s = 25.1 and min_period_s = 1.5 reproduces the study's fixed sample counts on a 10 Hz recording.

That difference shows up in the published cohort means. All 34,095 of the study's slow-gait (MG) cycles come from 50 Hz recordings, and this function returns their published mean duration of 0.719 s exactly. The MH and MS means, 0.748 s and 0.773 s, mix in 10 Hz recordings; on the 50 Hz half alone both this function and the study give 0.650 s and 0.726 s.

See Also

pr_calc_dominant_freq() for the frequency-domain estimate of the same rhythm, pr_calc_phase_map() to average the sensor map over these cycles.

Other temporal structure functions: pr_calc_dominant_freq(), pr_calc_phase_map(), pr_calc_spectrum(), pr_cop_shape()

Examples

trial <- pr_example_trial("saddle_horse")
cycles <- pr_calc_stride_cycles(trial)
nrow(cycles)
round(range(cycles$duration_s), 2)

# stride_freq is the reciprocal of duration_s, cycle by cycle:
all.equal(cycles$stride_freq, 1 / cycles$duration_s)

# Cycles tile the recording end to end: each one starts where the
# previous accepted one stopped, unless an interval was rejected.
head(cbind(cycles$start_idx, cycles$end_idx), 3)

Description

Computes the symmetry index (SI%) between left and right sides of a layout for a given parameter. SI = (L - R) / (0.5 * (L + R)) * 100.

Usage

pr_calc_symmetry_index(
  trial,
  parameter = c("peak_pressure", "mean_pressure", "force", "contact_area")
)

Arguments

Value

Numeric scalar. Positive values indicate left dominance.

Examples

pr_calc_symmetry_index(pr_example_trial("saddle_horse"))

Description

The classic asymmetry index (L - R) / (0.5 * (L + R)) * 100, computed on the per-sensor map rather than frame by frame. Negative values are right-biased, positive values left-biased, and zero is symmetric.

Usage

pr_calc_symmetry_map(
  trial,
  masks = NULL,
  statistic = "mean",
  denominator = c("grid", "loaded")
)

Arguments

Details

L and R are the mean of the per-sensor map over the left and right sensors of the region of interest. Because the map is taken first, the index describes where load sat over the whole recording, not where the loudest frame happened to be; it is the counterpart of the frozen pr_calc_symmetry_index(), which averages within frames.

denominator chooses what goes into each side's mean:

• "grid" (default) averages over every sensor of the side, counting never-loaded ones as zeros. This is the cohort definition: on a mat that is the region of interest, an unloaded cell is a real measurement.

• "loaded" averages only the sensors whose map value is above zero. That answers a different question — how hard the loaded cells were pressed, ignoring how many there were — and is usually much closer to zero, because a side that loses contact area keeps its intensity.

The index is undefined when both sides are zero; that case returns 0, as pr_calc_symmetry_index() does.

Nothing here forces the two sides to hold the same number of sensors. When they do not, part of the index is a property of the mask — see pr_mask_mirror_balance() and pr_symmetry_sensitivity().

Value

A one-row tibble::tibble with columns statistic, denominator, n_left, n_right, left_value, right_value and asymmetry_pct.

See Also

pr_calc_symmetry_index() for the frame-first version, pr_symmetry_sensitivity() to vary the mask.

Other regional symmetry functions: pr_calc_cop_masked(), pr_calc_regional_map(), pr_mask_mirror_balance(), pr_mask_rowbands(), pr_symmetry_sensitivity()

Examples

trial <- pr_example_trial("saddle_horse")
pr_calc_symmetry_map(trial)

# Restricted to the cranial band only:
bands <- pr_mask_rowbands(trial$layout, sides = FALSE)
pr_calc_symmetry_map(trial, bands$cranial)

# Intensity-only comparison, ignoring how much area each side loaded:
pr_calc_symmetry_map(trial, denominator = "loaded")$asymmetry_pct

Description

Sum of all sensor readings in each frame.

Usage

pr_calc_total_pressure(trial)

Arguments

Details

The result is a sum of pressures (kPa), not a force. Converting it to Newtons requires a per-cell area; pr_calc_force() does that using layout$sensor_area_cm2. For devices whose cell pitch was never published, sensor_area_cm2 is NA and no force value is defensible — hence this raw kPa sum, which is what the cohort analyses use. It is the unscaled counterpart of pr_calc_mean_pressure_grid() (total / n_sensors).

Value

Numeric vector of length n_frames, summed pressure per frame.

See Also

Other whole-grid frame metrics: pr_calc_cop_grid(), pr_calc_loaded_count(), pr_calc_mean_pressure_grid(), pr_calc_pci(), pr_frame_metrics(), pr_ref_pci()

Examples

trial <- pr_example_trial("saddle_horse")
tot <- pr_calc_total_pressure(trial)
round(max(tot), 1)

Description

Returns the integer permutation that reorders the columns of a raw device export into the column-major grid order every other pressR function assumes. A reader applies it once: pressure <- raw[, pr_channel_order(layout), drop = FALSE].

Usage

pr_channel_order(layout_or_map)

Arguments

Details

Element k of the result is the device channel that belongs in pressure column k, where column k corresponds to which(layout$active)[k] — the same column-major ordering used by pr_mask() and .layout_build_coords().

Value

An integer vector of length layout$n_sensors.

See Also

Other channel map functions: pr_layout_from_index_map(), pr_layout_saddle_novel()

Examples

pr_channel_order(rbind(c(2L, 1L), c(4L, 3L)))

ord <- pr_channel_order(pr_layout_saddle_novel())
length(ord)
ord[1:8]

Description

Construct a pr_cop object from x/y coordinates and time. Normally created by pr_calc_cop() rather than called directly.

Usage

pr_cop(x, y, time)

Arguments

Value

A pr_cop S3 object with fields x, y, time, path_length, velocity_mean, velocity_max, range_x, range_y, sway_area.

Description

Describes a centre-of-pressure trajectory as a loop: how far its end lands from its start, and whether the path crosses itself on the way.

Usage

pr_cop_shape(cop, close = TRUE)

Arguments

Details

A stride that returns the rider to where they began traces a closed loop, and how that loop is shaped separates a clean, repeatable seat from a wandering one. Two numbers capture most of it:

• closure_dist — the straight-line distance from the last point back to the first, in whatever units the trajectory carries. Small relative to the path travelled means the trajectory came home.

• n_crossings — how many times the path cuts through itself. A simple oval crosses zero times; a figure-of-eight crosses once; a trajectory that scribbles crosses many times. self_intersects is n_crossings > 0.

With close = TRUE (default) the first point is appended to the end before the crossing sweep, so the closing chord counts as part of the loop — the right question for a cycle that should repeat. With close = FALSE only the path as travelled is examined. Either way closure_dist and path_length describe the open trajectory.

Crossings are counted with orientation tests on every pair of non-adjacent segments, an exact predicate with no tolerance to tune. Two segments that merely touch end to end, or that overlap along a line, are not counted; only a genuine transverse crossing is. The sweep is quadratic in the number of points, which is immaterial for one stride and worth remembering before feeding it a whole recording.

Units are the input's own and nothing is converted: a pr_cop from pr_calc_cop() is in millimetres, while cop_row/cop_col from pr_calc_cop_grid() or pr_frame_metrics() are in grid index units, so path_length and closure_dist follow suit. closure_ratio is dimensionless and comparable across both.

Missing coordinates are dropped pairwise before anything is measured — pr_calc_cop() returns NA for unloaded frames.

Value

A one-row tibble::tibble with columns n_points (integer, after dropping missing coordinates), path_length, closure_dist, closure_ratio (closure_dist / path_length, NA for a stationary trajectory), self_intersects (logical) and n_crossings (integer).

See Also

pr_calc_cop_grid() and pr_frame_metrics() for trajectories in grid units, pr_calc_cop() for millimetres.

Other temporal structure functions: pr_calc_dominant_freq(), pr_calc_phase_map(), pr_calc_spectrum(), pr_calc_stride_cycles()

Examples

# A clean rectangle: comes home, never crosses itself.
square <- data.frame(x = c(0, 1, 1, 0), y = c(0, 0, 1, 1))
pr_cop_shape(square)

# A bow tie crosses once.
bow <- data.frame(x = c(0, 1, 0, 1), y = c(0, 0, 1, 1))
pr_cop_shape(bow)$n_crossings

# One stride of a real trajectory, in grid index units:
trial <- pr_example_trial("saddle_horse")
cycles <- pr_calc_stride_cycles(trial)
cop <- pr_calc_cop_grid(trial)
pr_cop_shape(cop[cycles$start_idx[1]:cycles$end_idx[1], ])

Description

A pr_dataset is a collection of pr_trial objects with shared grouping metadata, intended for batch analysis.

Usage

pr_dataset(trials, group_var = "condition", name = "dataset")

Arguments

Value

A pr_dataset S3 object.

Examples

t1 <- pr_example_trial("insole", seed = 1)
t2 <- pr_example_trial("insole", seed = 2)
ds <- pr_dataset(list(t1, t2))
print(ds)

Description

Keeps the trials whose metadata satisfy a predicate, records the filter label on the returned dataset, and — when n_units or n_subjects are given — asserts that the surviving cohort has exactly the expected size. The assertion is the point: a cohort step that cannot fail cannot protect a result.

Usage

pr_dataset_filter(
  dataset,
  f,
  label = NULL,
  n_units = NULL,
  n_subjects = NULL,
  subject_field = "ID"
)

Arguments

Value

A pr_dataset containing the surviving trials, with extra elements filter_label and filter_history.

See Also

Other cohort functions: pr_assert_cohort(), pr_design_table(), pr_validate_dataset()

Examples

layout <- pr_layout_mat("16")
mk <- function(id, mode) {
  pr_trial(matrix(1, 3, layout$n_sensors), time = c(0, 0.02, 0.04),
           layout = layout, metadata = list(ID = id, Mode = mode))
}
ds <- pr_dataset(list(mk("ID001", "MS"), mk("ID001", "MH"),
                      mk("ID002", "MS")))
walk <- pr_dataset_filter(ds, ~ .x$Mode == "MS", label = "walk",
                          n_units = 2, n_subjects = 2)
walk$filter_label

Description

Crosses the levels of the named factors, counts how many rows fall in each cell, and labels every cell of the crossing as missing, under-represented, balanced, or over-represented. This is what surfaces a nesting or aliasing problem before anything is modelled.

Usage

pr_design_gaps(x, factors, expected = NULL)

Arguments

Details

A design described as "all saddles crossed with all pads" can turn out to be nothing of the sort: one pad may only ever have been used with one saddle, in which case the two factors are aliased and their effects are not separately estimable — a fact no model summary will state out loud. Counting the cells of the full crossing shows it immediately: a factor nested inside another leaves whole blocks of the crossing at n == 0.

Levels come from levels() for a factor column and from the sorted unique non-NA values otherwise. Sorting uses method = "radix", which forces C-locale collation, so the row order of the result does not depend on the machine's locale. The crossing is generated by tidyr::expand_grid(), so the first factor varies slowest and the row order is the natural nesting order.

expected sets the replicate count a balanced cell should hold. Left NULL, it is the most common non-zero cell count — the design's own idea of a full cell — with ties broken towards the larger count, so a tie errs towards reporting cells as under-represented rather than as balanced.

Rows with NA in any crossing factor cannot be placed in a cell. They are dropped and a warning names how many, because dropping them silently would understate the gaps.

Value

A tibble::tibble with one row per cell of the full crossing: the factor columns (as character), then n (rows observed), expected, delta (n - expected) and status, one of "missing" (n == 0), "under", "ok" or "over".

See Also

pr_factor_contract() for the level sets being crossed, pr_design_table() for building x from a pr_dataset.

Other provenance functions: pr_factor_contract(), pr_lock_table(), pr_validate_summary(), pr_verify_lock()

Examples

design <- data.frame(
  Saddle = c("K", "K", "K", "S", "S", "W"),
  Pad = c("F", "K", "K", "F", "F", "W")
)
gaps <- pr_design_gaps(design, c("Saddle", "Pad"))
gaps

# Pad is nested within Saddle, not crossed with it:
sum(gaps$status == "missing")

# With an explicit replicate expectation:
pr_design_gaps(design, c("Saddle", "Pad"), expected = 2)

Description

Reduces a pr_dataset to one row per trial: the chosen metadata fields plus n_frames and duration_s. This is the study design as a table — the object you count, cross-tabulate, and assert against with pr_assert_cohort().

Usage

pr_design_table(dataset, fields = NULL)

Arguments

Details

duration_s is the trial's duration field, i.e. diff(range(time)), so a 23432-frame recording at 50 Hz gives 468.62 s (not 468.64 s).

Value

A tibble::tibble with one row per trial and columns fields, n_frames (integer) and duration_s (numeric).

See Also

Other cohort functions: pr_assert_cohort(), pr_dataset_filter(), pr_validate_dataset()

Examples

layout <- pr_layout_mat("16")
mk <- function(id, mode, n) {
  pr_trial(
    matrix(1, n, layout$n_sensors),
    time = seq(0, (n - 1) / 50, by = 1 / 50),
    layout = layout,
    metadata = list(ID = id, Mode = mode)
  )
}
ds <- pr_dataset(list(mk("ID001", "MS", 4), mk("ID002", "MH", 6)))
pr_design_table(ds, fields = c("ID", "Mode"))

Description

Keeps every factor-th frame.

Usage

pr_downsample(trial, factor = 2L)

Arguments

Value

A pr_trial object with reduced frame count.

Examples

tr <- pr_downsample(pr_example_trial("insole"), factor = 2)
tr$n_frames

Description

Creates sample ASCII files in a temporary directory for demonstrating the parser functions.

Usage

pr_example_files(type = c("insole", "saddle", "platform", "all"))

Arguments

Value

Character. Path to the sample file (single type) or directory ("all").

Examples

path <- pr_example_files("insole")
file.exists(path)

Description

Creates a pr_trial with realistic synthetic pressure data for demonstration, testing, and vignette purposes.

Usage

pr_example_trial(
  type = c("insole", "platform", "saddle_horse", "saddle_bicycle", "wheelchair",
    "custom"),
  duration_s = NULL,
  sampling_hz = 50,
  seed = 42
)

Arguments

Value

A pr_trial object.

Examples

trial <- pr_example_trial("insole")
print(trial)

Description

Export Analysis Results to CSV

Usage

pr_export_csv(
  trial,
  path,
  what = c("summary", "regional", "pressure", "cop"),
  masks = NULL
)

Arguments

Value

Invisibly returns the written file path.

Examples

tmp <- tempfile(fileext = ".csv")
pr_export_csv(pr_example_trial("insole"), tmp, what = "summary")

Description

Renders a parameterized R Markdown template into an HTML or PDF report for a trial.

Usage

pr_export_report(
  trial,
  output_file,
  format = c("html", "pdf"),
  template = c("generic", "saddle", "foot"),
  masks = NULL,
  thresholds = NULL
)

Arguments

Value

Invisibly returns the generated file path.

Examples

## Not run: 
tmp <- tempfile(fileext = ".html")
pr_export_report(pr_example_trial("insole"), tmp, template = "foot")

## End(Not run)

Description

Checks that named columns of a data frame carry exactly the levels they are contracted to carry — no unexpected value, no silently absent level, and for factor columns the declared order as well. Aborts naming the offending column, the offending values, and the rows they sit in.

Usage

pr_factor_contract(x, levels_list, id_cols = NULL)

Arguments

Details

This is the check that catches a typo'd condition code, a level lost to a filter, and a factor() call whose ⁠levels =⁠ argument drifted out of step with the data — all of which change a model's reference level or its contrast matrix without changing anything visible in a head().

Both directions are enforced, because "exactly" is the point: a value in the data that the contract does not list is an unexpected_level, and a level in the contract that never appears in the data is a missing_level. The second half is the one that matters after a subset — a design that lost a whole condition still looks perfectly well formed.

Order is enforced only where order exists. A factor column stores its levels, so levels(x[[col]]) must equal the contract element by element; a mismatch in order alone is reported as wrong_order. A character column has no stored order, so only its level set is contracted — convert with factor(x, levels = ...) first if the order has to be pinned.

NA values are reported as missing_value unless NA appears in the contract for that column, in which case they are accepted.

Value

Invisibly, x — so the contract can sit inside a pipeline. On violation, aborts with condition class pr_factor_contract_failed, carrying a problems tibble::tibble (columns column, issue, value, n_rows, ids) in the condition.

See Also

pr_design_gaps() for the combinations those levels do and do not form.

Other provenance functions: pr_design_gaps(), pr_lock_table(), pr_validate_summary(), pr_verify_lock()

Examples

design <- data.frame(
  ID = c("ID001", "ID001", "ID003", "ID003"),
  Mode = c("MG", "MH", "MS", "MH"),
  Saddle = c("K", "S", "W", "K")
)

# Passes and returns the data invisibly:
out <- pr_factor_contract(
  design,
  list(Mode = c("MG", "MH", "MS"), Saddle = c("K", "S", "W")),
  id_cols = "ID"
)
identical(out, design)

# A wrong contract fails loudly, naming the column and the values:
try(pr_factor_contract(design, list(Mode = c("MG", "MH"))))

Description

Subset a Trial to a Time Window

Usage

pr_filter_time(trial, from = 0, to = Inf)

Arguments

Value

A pr_trial containing only frames with time in ⁠[from, to]⁠.

Examples

tr <- pr_filter_time(pr_example_trial("insole"), from = 1, to = 3)
tr$duration

Description

Computes the whole-grid frame vocabulary — mean, peak, total, loaded cell count and grid-index centre of pressure — in a single vectorised pass over the pressure matrix.

Usage

pr_frame_metrics(trial, threshold = 0, eps = 1e-12)

Arguments

Details

Every column is computed with whole-matrix operations — two rowSums(), one max.col(), and a single matrix product carrying both COP axes. There is no per-frame R loop, because cohort-scale inputs run to millions of frames. Measured on a 200,000 x 256 matrix (R 4.6.1, one core): about 145,000 frames per second, i.e. roughly 70 s for a 5.5 M-frame cohort, against 73-83 s for the equivalent vapply() over rows. The default threshold = 0 also skips masking the matrix entirely when no reading is negative, which saves a full copy of the pressure data.

Column definitions:

• mean_kPa — total_kPa / n_sensors, whole grid, zeros included. This is not pr_calc_mean_pressure(), which is loaded-cells-only by definition and is left unchanged; see pr_calc_mean_pressure_grid().

• peak_kPa — the plain row maximum, not filtered by threshold.

• total_kPa — the plain row sum, not filtered by threshold.

• loaded — count of cells strictly above threshold.

• cop_row, cop_col — grid index units, eps on the denominator so an unloaded frame gives approximately 0 rather than NA.

threshold therefore affects loaded and the COP weighting only; peak and total always describe the frame as recorded.

Value

A tibble::tibble with n_frames rows and columns frame, time_s, mean_kPa, peak_kPa, total_kPa, loaded, cop_row, cop_col. Pressure columns carry the trial's own unit; the kPa suffixes follow the cohort naming convention.

See Also

Other whole-grid frame metrics: pr_calc_cop_grid(), pr_calc_loaded_count(), pr_calc_mean_pressure_grid(), pr_calc_pci(), pr_calc_total_pressure(), pr_ref_pci()

Examples

trial <- pr_example_trial("saddle_horse")
fm <- pr_frame_metrics(trial)
names(fm)
all.equal(fm$mean_kPa, fm$total_kPa / trial$layout$n_sensors)

Description

Performs bilinear interpolation on the maximum pressure picture between active sensor positions to produce a smoother image. The underlying trial data is not modified.

Usage

pr_interpolate(trial, factor = 2L)

Arguments

Value

A list with pressure_interp (interpolated matrix), x_mm, y_mm.

Examples

out <- pr_interpolate(pr_example_trial("insole"), factor = 2)
dim(out$pressure_interp)

Description

Defines the physical arrangement of sensors in a pressure measurement system, including grid dimensions, active sensor positions, physical coordinates, and named region masks.

Usage

pr_layout(
  grid_rows,
  grid_cols,
  active,
  coords_mm,
  regions = list(),
  sensor_area_cm2 = 1,
  pressure_range = c(0, 600),
  pressure_unit = "kPa",
  name = "custom",
  description = "",
  manufacturer = "",
  model = ""
)

Arguments

Value

A pr_layout S3 object (list with class attribute).

Examples

active <- matrix(TRUE, 4, 4)
coords <- data.frame(
  sensor_id = seq_len(16),
  row = rep(1:4, each = 4),
  col = rep(1:4, times = 4),
  x_mm = rep(seq(0, 30, 10), times = 4),
  y_mm = rep(seq(0, 30, 10), each = 4)
)
layout <- pr_layout(4, 4, active, coords, name = "example_4x4")
print(layout)

Description

Creates a pr_layout from a matrix that states, for every grid cell, which device channel is wired to it. This is the general answer to the problem that a sensor mat's channel numbering rarely matches the order in which the grid is read. The resulting layout carries the map with it, so pr_channel_order() can hand a reader the one permutation that puts raw device columns into the column-major grid order that pr_mask(), pr_calc_cop() and the plotting functions already assume.

Usage

pr_layout_from_index_map(
  index_matrix,
  name = "custom",
  sensor_area_cm2 = NA_real_,
  spacing_mm = NA_real_,
  pressure_range = NULL,
  ...
)

Arguments

Value

A pr_layout object with three extra fields: channel_map (the validated integer map, NA for empty cells), channel_order (the permutation returned by pr_channel_order()) and coords_units.

Missing physical scale

pr_layout() requires a positive sensor_area_cm2 and physical x_mm / y_mm coordinates. Many real datasets have neither: the cell area and the sensor pitch were simply never recorded. Rather than invent a number, this function

• builds the object through pr_layout() with a placeholder area and then writes NA_real_ into sensor_area_cm2, so the layout stays a valid pr_layout and pr_validate_layout() still passes, while anything derived from area (force in N, contact area in cm²) honestly returns NA; and

• when spacing_mm is NA, lays the coordinates out on a unit grid (x_mm = col - 1, y_mm = row - 1). Ordering, masks and centre of pressure are then all correct, but the x_mm / y_mm columns are grid-index offsets, not millimetres — a COP of x_mm = 8 means column 9, not 8 mm. The layout records this in ⁠$coords_units⁠ ("grid_index" or "mm") and keeps the requested pitch in ⁠$spacing_mm⁠.

Supply a real sensor_area_cm2 / spacing_mm and the layout behaves as a fully physical one. Note that plot.pr_layout() sizes region tiles from sensor_area_cm2, so pass regions only alongside a real area.

See Also

Other channel map functions: pr_channel_order(), pr_layout_saddle_novel()

Examples

# A 2x2 mat whose channels are wired right-to-left within each row.
m <- rbind(c(2L, 1L), c(4L, 3L))
lay <- pr_layout_from_index_map(m, name = "toy_2x2")
lay$n_sensors
pr_channel_order(lay)

# Raw device frame: only channel 1 is loaded.
raw <- matrix(c(10, 0, 0, 0), nrow = 1)
grid_cols <- raw[, pr_channel_order(lay), drop = FALSE]
# Channel 1 is at grid (1, 2), i.e. the 3rd cell in column-major order.
which(grid_cols[1, ] > 0)

Description

Returns a pr_layout for a glove-style hand pressure sensor (32 sensors across palm and fingertips).

Usage

pr_layout_glove()

Value

A pr_layout object.

Description

Returns a pr_layout representing a typical in-shoe pressure measurement insole. The insole contains 99 capacitive sensors arranged in an anatomically shaped grid.

Usage

pr_layout_insole(size = c("standard", "wide"))

Arguments

Value

A pr_layout object with predefined foot region masks.

Examples

layout <- pr_layout_insole()
print(layout)

Description

List All Built-In Sensor Layouts

Usage

pr_layout_list()

Value

A tibble::tibble with columns name, system, grid_rows, grid_cols, n_sensors, n_regions, description.

Examples

pr_layout_list()

Description

Returns a pr_layout for a generic capacitive pressure sensor mat. These general-purpose sensor arrays are used in research, seating, sports, and ergonomics applications.

Usage

pr_layout_mat(size = c("16", "32"))

Arguments

Value

A pr_layout with no predefined regions.

Description

Returns a pr_layout for a barefoot pressure platform. Provides high-resolution plantar pressure distribution during static and dynamic conditions.

Usage

pr_layout_platform(model = c("st", "xl", "cl"))

Arguments

Value

A pr_layout object. Region masks are not predefined — use pr_mask_foot_auto() to auto-segment footprints from the data.

Examples

layout <- pr_layout_platform()
layout$grid_rows
layout$grid_cols

Description

Returns a pr_layout for saddle pressure measurement using a capacitive sensor mat. Includes predefined region masks based on published research protocols.

Usage

pr_layout_saddle(type = c("horse", "bicycle"))

Arguments

Value

A pr_layout with application-specific region masks.

Examples

layout <- pr_layout_saddle("horse")
names(layout$regions)

Description

The ready-made layout for the two-panel 16 x 16 (256 sensor) capacitive saddle mat exported by Novel/Pliance systems. All 256 sensors are active.

Usage

pr_layout_saddle_novel(
  pressure_range = c(0, 63.75),
  sensor_area_cm2 = NA_real_,
  ...
)

Arguments

Details

The mat is built from two 16 x 8 panels. Device channel 1 sits at grid (row 1, column 9) — the first cell of the right panel — and channel 9 at (row 1, column 8), with each grid row advancing the channel number by 16 and the left panel running right-to-left. Applying pressure[, pr_channel_order(layout)] to a raw export therefore places every channel at its true anatomical position, which is what makes pr_mask_saddle_6(), pr_mask_symmetry(), pr_calc_cop() and the heatmaps simultaneously correct. Without the permutation the aggregate statistics (mean, peak, total) are unchanged, so a wrong map is invisible in every summary and wrong in every map.

No sensor pitch or cell area is published for this mat, so both default to NA and the coordinates are grid indices — see the Missing physical scale section of pr_layout_from_index_map().

Value

A pr_layout with 256 active sensors and a channel_map field.

See Also

Other channel map functions: pr_channel_order(), pr_layout_from_index_map()

Examples

layout <- pr_layout_saddle_novel()
layout$n_sensors
layout$channel_map[1, 1:10]

# Device channel 1 lands at grid (row 1, col 9):
pos <- match(1L, pr_channel_order(layout))
layout$coords_mm[pos, c("row", "col")]

Description

Returns a pr_layout for seating pressure assessment. Uses a 32x32 grid (1024 sensors) with application-specific regions.

Usage

pr_layout_seat(type = c("wheelchair", "car", "office"))

Arguments

Value

A pr_layout object.

Description

Writes a sidecar lock file recording a data frame's row count, column count, column names, column types and a content hash. Committed next to the analysis, it turns "the input has not changed" from an assumption into something pr_verify_lock() can check.

Usage

pr_lock_table(x, path, algo = "md5")

Arguments

Details

The hash is md5 — tools::md5sum() is the only hash function in base R — computed over a byte stream this function writes itself: a fixed magic string, then for each column an NA mask of one byte per row followed by the values as big-endian IEEE-754 doubles, 4-byte big-endian integers, or NUL-terminated UTF-8 strings.

That stream is used in preference to the two obvious alternatives because both are unstable in ways that would make a lock fail for the wrong reason:

• utils::write.csv() renders doubles as decimal text. R 4.3.0 changed how as.character() formats doubles, so identical numbers can produce different bytes under different R versions, and decimal text does not round-trip a double in any case.

• serialize() writes the R version that produced the stream into its own header, so the same object hashes differently under R 4.3 and R 4.6.

Pinning the byte order makes x86 and ARM agree; writing doubles as bits removes every formatting decision; carrying NA in a side mask means no real value can impersonate a missing one. Before hashing, each column is reduced to a bare vector — factors to their labels, Date/POSIXct to seconds, all other attributes dropped — so a tibble::tibble and a data.frame holding the same numbers hash alike, and a class change is reported through the types line rather than as a content change.

Column names and types are recorded but are deliberately not part of the content hash. That is what lets pr_verify_lock() distinguish a pure rename ("columns changed, content unchanged") from an edit to the data.

No timestamp is written. Re-locking an unchanged table leaves the file byte-identical, so a lock file under version control produces a diff only when the table really moved.

List columns cannot be hashed and are rejected with an error rather than skipped, because a silently unhashed column is worse than no lock at all.

Value

Invisibly, a one-row tibble::tibble with columns path, algo, nrow, ncol, columns (list of character), types (list of character) and content (the hash).

See Also

pr_verify_lock() to check a table against a lock file.

Other provenance functions: pr_design_gaps(), pr_factor_contract(), pr_validate_summary(), pr_verify_lock()

Examples

design <- data.frame(
  ID = c("ID001", "ID001", "ID003"),
  Mode = c("MH", "MS", "MG"),
  n_frames = c(23432L, 10662L, 8000L)
)
path <- tempfile(fileext = ".lock")
lock <- pr_lock_table(design, path)
lock$content

# Locking is deterministic: the same table gives the same file.
path2 <- tempfile(fileext = ".lock")
pr_lock_table(design, path2)
identical(readLines(path), readLines(path2))

unlink(c(path, path2))

Description

Wraps a logical matrix describing a named region over a sensor layout.

Usage

pr_mask(mask_matrix, name, layout)

Arguments

Value

A pr_mask S3 object.

Examples

layout <- pr_layout_saddle("horse")
m <- layout$regions$cranial_left
pr_mask(m, "cranial_left", layout)

Description

Returns a named list of numeric matrices. Each entry has dimensions ⁠n_frames x n_sensors_in_region⁠ and contains the pressure values of that region's sensors for each frame.

Usage

pr_mask_apply(trial, masks = NULL)

Arguments

Value

Named list of numeric matrices.

Examples

trial <- pr_example_trial("saddle_horse")
reg <- pr_mask_apply(trial)
vapply(reg, ncol, integer(1))

Description

Returns a named list of pr_mask objects built from the regions field of a pr_layout.

Usage

pr_mask_default(layout)

Arguments

Value

Named list of pr_mask objects (possibly empty).

Examples

masks <- pr_mask_default(pr_layout_saddle("horse"))
names(masks)

Description

For platform recordings where foot regions must be detected from the raw pressure matrix. Uses the maximum pressure picture (MPP) to identify the foot outline, then segments into anatomical regions based on proportional geometry.

Usage

pr_mask_foot_auto(trial, n_regions = 7L, threshold = 1)

Arguments

Value

Named list of pr_mask objects.

Description

Trims a region mask down to the cells whose mirror image across the mat's midline is also in the mask. The result is symmetric by construction, so a left/right comparison made on it cannot be an artefact of one side simply owning more sensors than the other.

Usage

pr_mask_mirror_balance(mask, layout, axis = c("vertical", "horizontal"))

Arguments

Details

This is the largest mirror-symmetric subset of the input: a cell survives if and only if both it and its reflection were present, and no mirror-symmetric superset of that set exists inside the mask. The two halves of the result are exact reflections of each other, which is a stronger guarantee than equal counts.

The reason to want it is that an asymmetry index divides by the mean of the two sides. If the region of interest happens to contain more cells on one side — because a sensor died, or because a data-driven mask was built from a load pattern that is itself lopsided — then part of the resulting index measures the mask, not the horse. In the study cohort, dropping sensors that were flat for more than 95% of every recording left 106 live cells on the left and 117 on the right; balancing to 106/106 moved the cohort median asymmetry from -30.5% to -39.0%, the second of which agrees with the whole-grid figure and the first of which does not.

Cells outside layout$active are never kept. When the axis has an odd number of lines the centre line reflects onto itself and belongs to neither half, so it is dropped; on an even grid (such as the 16 x 16 saddle mat) nothing is lost to this.

Value

A pr_mask object carrying two extra fields: axis, and halves, a named integer vector of the two sides' sensor counts, which are equal by construction.

See Also

pr_symmetry_sensitivity(), which applies this across a family of masks.

Other regional symmetry functions: pr_calc_cop_masked(), pr_calc_regional_map(), pr_calc_symmetry_map(), pr_mask_rowbands(), pr_symmetry_sensitivity()

Examples

layout <- pr_layout_saddle("horse")

# A deliberately lopsided region: all of the left half, but only three
# columns of the right.
m <- matrix(FALSE, 16, 16)
m[, 1:8] <- TRUE
m[, 9:11] <- TRUE
bal <- pr_mask_mirror_balance(m, layout)
bal$halves

# The surviving columns are 6:11 -- the ones with a partner on both sides.
which(apply(bal$matrix, 2, any))

Description

Builds cranial / middle / caudal row bands (optionally crossed with the left and right halves of the mat) from stated split rows rather than from a derived floor(grid_rows / 3). The split is the argument, so a study's own band definition survives into the code instead of being approximated by a division.

Usage

pr_mask_rowbands(
  layout,
  breaks = c(5, 11),
  sides = TRUE,
  band_names = c("cranial", "middle", "caudal")
)

Arguments

Details

breaks gives the last row of each band except the last. With the default c(5, 11) on a 16-row mat the bands are rows 1:5, 6:11 and 12:16 — the split used by pr_layout_saddle()'s regions, in which the middle band is one row deeper than the outer two.

pr_mask_saddle_6() uses third <- floor(16 / 3), which gives 1:5, 6:10, 11:16 instead: the caudal band is the deep one. Passing breaks = c(5, 10) reproduces those cells exactly, with the same names in the same order, so the two conventions can be compared rather than confused. Because that one-row difference moves eight sensors between two zones, it is worth stating which convention a number came from.

Left and right are split at floor(grid_cols / 2), matching pr_mask_symmetry() and pr_mask_saddle_6(). With sides = TRUE the masks come back in band-major order (cranial_left, cranial_right, middle_left, ...); with sides = FALSE there is one full-width mask per band. Every mask is intersected with layout$active, so inactive cells (a withers cutout, say) never enter a band.

Value

A named list of pr_mask objects: length(band_names) of them when sides = FALSE, twice that when sides = TRUE.

See Also

pr_mask_saddle_6() for the derived-thirds convention, pr_calc_regional_map() which consumes these masks.

Other regional symmetry functions: pr_calc_cop_masked(), pr_calc_regional_map(), pr_calc_symmetry_map(), pr_mask_mirror_balance(), pr_symmetry_sensitivity()

Examples

layout <- pr_layout_saddle("horse")
masks <- pr_mask_rowbands(layout)
names(masks)
vapply(masks, function(m) m$n_sensors, integer(1))

# breaks = c(5, 10) is the pr_mask_saddle_6() convention:
same <- pr_mask_rowbands(layout, breaks = c(5, 10))
identical(same$middle_left$matrix, pr_mask_saddle_6(layout)$middle_left$matrix)

# Full-width bands, no left/right split:
names(pr_mask_rowbands(layout, sides = FALSE))

Description

Creates the 6-region saddle pressure analysis mask dividing the sensor mat into cranial / middle / caudal thirds crossed with left / right halves, as established by Werner et al. (2002) and used in subsequent equine back-pressure studies.

Usage

pr_mask_saddle_6(layout)

Arguments

Value

Named list of 6 pr_mask objects.

Examples

pr_mask_saddle_6(pr_layout_saddle("horse"))

Description

Produces a two-element named list of pr_mask objects dividing the layout along the specified axis.

Usage

pr_mask_symmetry(layout, axis = c("vertical", "horizontal"))

Arguments

Value

A named list of two pr_mask objects.

Examples

pr_mask_symmetry(pr_layout_saddle("horse"))

Description

Merge Trials into a Dataset

Usage

pr_merge_trials(..., group_var = "condition")

Arguments

Value

A pr_dataset object.

Examples

pr_merge_trials(
  pr_example_trial("insole", seed = 1),
  pr_example_trial("insole", seed = 2)
)

Description

Many measurement archives encode a recording's design cells in its file name, e.g. ID052_K_K_KG00_MS.asc for subject ID052, saddle K, pad K, weight KG00, mode MS. This splits such a base name into a one-row tibble of named fields.

Usage

pr_meta_from_filename(
  path,
  fields,
  sep = "_",
  on_fail = c("skip", "error", "na")
)

Arguments

Details

A name matches only when it splits into exactly length(fields) non-empty parts. That strictness is the point: it is what lets a directory read reject stray files (repeat takes such as ID003_K_K_KG60_MH_R01, notes, exports) instead of silently mislabelling them.

Value

A one-row tibble with one character column per entry of fields, or NULL (see on_fail).

See Also

Other Pliance ingest functions: pr_read_dir(), pr_read_pliance()

Examples

fields <- c("ID", "Saddle", "Pad", "Weight", "Mode")
pr_meta_from_filename("ID052_K_K_KG00_MS.asc", fields)

# A repeat take carries a sixth part, so it does not match:
pr_meta_from_filename("ID003_K_K_KG60_MH_R01.asc", fields)

pr_meta_from_filename("ID003_K_K_KG60_MH_R01.asc", fields, on_fail = "na")

Description

Renders a pressure frame as a 3D surface using plotly.

Usage

pr_plot_3d(trial, frame = NULL, palette = "viridis")

Arguments

Value

A plotly object.

Examples

pr_plot_3d(pr_example_trial("saddle_horse"))

Description

Produces a side-by-side heatmap comparison, a difference map, or a parameter-table plot for two trials.

Usage

pr_plot_comparison(
  trial_a,
  trial_b,
  type = c("heatmap", "difference", "parameters"),
  labels = c("A", "B")
)

Arguments

Value

A ggplot2 (or patchwork) object.

Examples

a <- pr_example_trial("insole", seed = 1)
b <- pr_example_trial("insole", seed = 2)
pr_plot_comparison(a, b, type = "difference")

Description

Plot Contact Area vs Time

Usage

pr_plot_contact_area(trial, show_cycles = FALSE)

Arguments

Value

A ggplot2 object.

Description

Plot Center of Pressure Trajectory

Usage

pr_plot_cop(trial, show_layout = TRUE, color_by = c("time", "velocity"))

Arguments

Value

A ggplot2 object.

Examples

pr_plot_cop(pr_example_trial("saddle_horse"))

Description

Overlays COP trajectories from each detected stance phase, centered on heel strike.

Usage

pr_plot_cop_butterfly(trial, cycles = NULL)

Arguments

Value

A ggplot2 object.

Examples

pr_plot_cop_butterfly(pr_example_trial("insole"))

Description

Composite figure for foot pressure analysis: MPP map, regional bar chart, force-time curve, COP trajectory.

Usage

pr_plot_foot_report(trial)

Arguments

Value

A patchwork object.

Examples

pr_plot_foot_report(pr_example_trial("insole"))

Description

Plot Force vs Time

Usage

pr_plot_force_time(trial, show_cycles = FALSE)

Arguments

Value

A ggplot2 object.

Examples

pr_plot_force_time(pr_example_trial("insole"))

Description

Displays a 2D heatmap for a single frame or a summary image (MPP, MVP, PTI, contact frequency).

Usage

pr_plot_heatmap(
  trial,
  frame = NULL,
  type = c("mpp", "mvp", "pti", "contact"),
  show_regions = FALSE,
  palette = "viridis",
  range = NULL,
  interpolate = FALSE,
  title = NULL
)

Arguments

Value

A ggplot2 object.

Examples

trial <- pr_example_trial("insole")
pr_plot_heatmap(trial)

Description

Convenience wrapper for pr_plot_heatmap() that always overlays region boundaries.

Usage

pr_plot_heatmap_masked(
  trial,
  masks = NULL,
  frame = NULL,
  type = c("mpp", "mvp", "pti", "contact"),
  palette = "viridis",
  range = NULL,
  title = NULL
)

Arguments

Value

A ggplot2 object.

Examples

pr_plot_heatmap_masked(pr_example_trial("saddle_horse"))

Description

Plot Peak and Mean Pressure vs Time

Usage

pr_plot_pressure_time(trial, show_cycles = FALSE)

Arguments

Value

A ggplot2 object.

Examples

pr_plot_pressure_time(pr_example_trial("insole"))

Description

Regional Parameter Comparison Bar Chart

Usage

pr_plot_regional_bar(regional_data, parameter = "mpp", thresholds = NULL)

Arguments

Value

A ggplot2 object.

Examples

trial <- pr_example_trial("saddle_horse")
reg <- pr_calc_regional(trial)
pr_plot_regional_bar(reg, "mpp")

Description

Composite figure for equine saddle analysis: MPP heatmap, 6-region bar chart, COP trajectory, and left/right symmetry summary.

Usage

pr_plot_saddle_report(trial, thresholds = NULL)

Arguments

Value

A patchwork object (4-panel composite).

Examples

pr_plot_saddle_report(pr_example_trial("saddle_horse"))

Description

Left/Right Symmetry Plot

Usage

pr_plot_symmetry(
  trial,
  parameter = c("peak_pressure", "mean_pressure", "force", "contact_area")
)

Arguments

Value

A ggplot2 object with a mirrored bar chart.

Examples

pr_plot_symmetry(pr_example_trial("saddle_horse"))

Description

Stacks pr_sensor_map() across every trial in a dataset: a ⁠n_trials x n_sensors⁠ numeric matrix whose rows are recordings and whose columns are sensors, in layout (column-major grid) order. This is the input stats::prcomp(), stats::dist(), stats::cmdscale() or a classifier expects, with no further reshaping.

Usage

pr_profile_matrix(dataset, statistic = "mean", threshold = 0)

Arguments

Details

Row names are the trials' identifying metadata (trial_id, else file_label, else subject_id, else ⁠trial_<i>⁠), made unique with make.unique(). Column names are ⁠sensor_<id>⁠ taken from the first trial's layout.

Every trial must expose the same number of sensors, since column k has to mean the same grid cell in every row; a mismatch is an error rather than a recycled row. Differing layout names at the same sensor count are only a warning: two layouts may legitimately share a grid, but if they do not, the matrix silently compares different anatomy, so the warning is worth reading.

Value

A numeric matrix with length(dataset) rows and n_sensors columns, with row and column names as described above.

See Also

pr_sensor_map() for a single trial.

Other sensor aggregation functions: pr_batch_frame_summary(), pr_sensor_map()

Examples

ds <- pr_dataset(lapply(1:3, function(s) {
  pr_example_trial("saddle_horse", seed = s)
}))
X <- pr_profile_matrix(ds, "mean")
dim(X)
X[, 1:4]

# Straight into a PCA of pressure distribution shape:
pc <- stats::prcomp(X)
round(pc$sdev[1:2], 3)

Description

Parses ASCII data files containing pressure sensor data. Automatically detects header format and extracts metadata, the pressure matrix, and timing.

Usage

pr_read_ascii(
  path,
  layout = NULL,
  sampling_hz = NULL,
  separator = "auto",
  skip = NULL,
  verbose = TRUE
)

Arguments

Value

A pr_trial object.

Examples

path <- pr_example_files("insole")
trial <- pr_read_ascii(path, verbose = FALSE)
trial$n_frames

Description

Inspects the file extension and header, then dispatches to the correct parser.

Usage

pr_read_auto(path, layout = NULL, verbose = TRUE)

Arguments

Value

A pr_trial object (for .asc / .txt / .csv), or a logical mask matrix / pr_mask object (for .msa/.msr/.msp).

Examples

path <- pr_example_files("insole")
tr <- pr_read_auto(path, verbose = FALSE)
inherits(tr, "pr_trial")

Description

Reads pressure data from a CSV file in either wide (one column per sensor) or long (tidy) format.

Usage

pr_read_csv(
  path,
  format = c("wide", "long"),
  layout = NULL,
  time_col = NULL,
  sampling_hz = 100,
  verbose = TRUE
)

Arguments

Value

A pr_trial object.

Examples

tmp <- tempfile(fileext = ".csv")
m <- matrix(runif(10 * 99, 0, 100), nrow = 10, ncol = 99)
utils::write.csv(m, tmp, row.names = FALSE)
trial <- pr_read_csv(tmp, format = "wide", layout = pr_layout_insole(),
                     verbose = FALSE)
trial$n_frames

Description

Walks a directory, reads every matching file with reader, and collects the results into a pr_dataset. Files that cannot be read - or whose names do not match meta_fields - are reported and skipped rather than aborting the whole batch.

Usage

pr_read_dir(
  dir,
  pattern = "\\.asc$",
  reader = pr_read_pliance,
  layout = NULL,
  meta_fields = NULL,
  recursive = TRUE,
  on_error = c("skip", "abort"),
  quiet = FALSE,
  ...,
  sep = "_",
  name = NULL
)

Arguments

Details

When meta_fields is supplied, each file name is split with pr_meta_from_filename() and the parts are stored in the trial's metadata under those names. The first part additionally fills subject_id and the remaining parts, rejoined with sep, fill condition - the field pr_dataset() groups by - unless the reader already set them. A name that does not split into exactly length(meta_fields) parts is skipped, which is the intended way to exclude repeat takes and stray exports from a cohort.

Value

A pr_dataset. Attribute "read_report" holds a tibble with one row per candidate file (file, path, status, reason).

See Also

Other Pliance ingest functions: pr_meta_from_filename(), pr_read_pliance()

Examples

dir <- tempfile()
dir.create(dir)
hdr <- c(
  "Dateiname:  demo.mat\tDatum/Zeit: 01.01.25 09.00",
  "Kalibrationsdatei:  demo_cal",
  "gesamte Messzeit [Sek.]: 0.040\tZeit pro Bild [Sek.]:  0.02000\tMessfrequenz [Hz]:   50",
  "Druckwerte in  kPa", "", "elektrisch:",
  "Zeit [Sek.]\t1\t2\t3\t4",
  "0.02000\t10\t0\t0\t0",
  "0.04000\t0\t20\t0\t0"
)
writeLines(hdr, file.path(dir, "ID001_K_KG00.asc"))
writeLines(hdr, file.path(dir, "ID002_K_KG40.asc"))
writeLines(hdr, file.path(dir, "ID002_K_KG40_R01.asc"))  # repeat take

lay <- pr_layout(
  2, 2, matrix(TRUE, 2, 2),
  data.frame(sensor_id = 1:4, row = c(1L, 2L, 1L, 2L),
             col = c(1L, 1L, 2L, 2L),
             x_mm = c(0, 0, 1, 1), y_mm = c(0, 1, 0, 1))
)
ds <- pr_read_dir(dir, layout = lay,
                  meta_fields = c("ID", "Saddle", "Weight"), quiet = TRUE)
length(ds)
attr(ds, "read_report")$status
unlink(dir, recursive = TRUE)