Package {DielectricWaterR}

Analyse descriptive dielectric ageing trajectories

Description

Summarises dielectric responses across ageing times at a fixed frequency and within the same material. Does not assume repeated measurements of one physical sample.

Usage

analyse_ageing_trajectories(
  data,
  outcome = "permittivity",
  frequency_hz,
  material = NULL
)

Arguments

Value

Data frame containing ageing time, mean response, number of measurements and descriptive changes.

Summarise dielectric frequency responses

Description

Provides descriptive summaries of dielectric measurements across experimental conditions and frequencies. Rows with unverified or conflicting water-medium labels are excluded from the primary analysis. No independent-sample inference is performed.

Usage

analyse_frequency_response(data, min_frequencies = 5L)

Arguments

Value

A tibble containing descriptive curve summaries.

Audit dielectric data without inventing physical sample IDs

Description

Audit dielectric data without inventing physical sample IDs

Usage

audit_dielectric(data)

Arguments

Value

List containing summary, missingness, ranges, duplicated keys and warnings.

Audit experimental-unit information

Description

Summarises measurements by material label and reports whether physical sample identities can be established. Material names are not assumed to identify physical samples.

Usage

audit_experimental_units(data, sample_id = NULL)

Arguments

Value

A data frame summarising material labels, ageing times, frequencies and sample identity status.

Examples

# Synthetic demonstration; not experimental observations.
x <- data.frame(
  material = rep(c('Water A', 'Water B'), each = 2),
  age_hours = c(0, 0, 0, 0),
  frequency_hz = c(10, 100, 10, 100),
  sample_id = c('A1', 'A1', 'B1', 'B1')
)

audit_experimental_units(x)
audit_experimental_units(x, sample_id = 'sample_id')

Audit observation exclusions for frequency-response analysis

Description

Classifies every observation according to its eligibility for the primary descriptive frequency-response analysis. Material-label agreement is a coding-consistency check, not independent verification of the experimental medium.

Usage

audit_frequency_exclusions(data)

Arguments

Value

A data frame containing the original observations, their row identifiers, expected water codes, medium-label status, and analysis inclusion decisions.

Compare dielectric measurements at two ageing times

Description

Matches measurements by fuel, water medium, concentration and frequency. Returns descriptive ratios between two ageing times. Ratios do not establish causal effects.

Usage

compare_ageing(data, age_start, age_end)

Arguments

Value

A data frame containing matched measurements and ratios for permittivity, dissipation factor and impedance.

Compare dielectric curves at exactly shared frequencies

Description

Uses only frequencies observed in every material-age group. Does not interpolate, extrapolate, or infer sample identity. At least two shared frequencies are required for AUC.

Usage

compare_common_frequency_curves(data, outcome = "permittivity")

Arguments

Value

A list with shared frequencies, aligned responses, and curve-level AUC summaries when possible.

Compare Matched Dielectric Fingerprints

Description

Compare petrol and diesel at identical experimental conditions using descriptive response ratios.

Usage

compare_dielectric_fingerprints(
  data,
  response = "permittivity",
  age_hours = 0,
  max_concentration = 20,
  exclude_conflicts = TRUE
)

Arguments

Value

A list containing matched results, summary, and duplicate-condition diagnostics.

Estimate confidence intervals using independent physical units

Description

Computes a Student t confidence interval for the mean response at a single experimental condition and frequency. Multiple measurements from one physical unit are averaged first. Physical sample identifiers must be externally verified.

Usage

estimate_dielectric_ci(
  data,
  outcome = "permittivity",
  sample_id,
  conf_level = 0.95
)

Arguments

Value

One-row data frame containing the mean, interval, and number of independent physical units.

Evaluate regression predictions

Description

Calculates descriptive prediction errors. Does not establish external-data independence.

Usage

evaluate_external_predictions(observed, predicted)

Arguments

Value

One-row data frame with n, MAE, RMSE and bias.

Plot dielectric frequency-response curves

Description

Produces descriptive frequency-response curves by material and recorded ageing time. Curves do not establish independent physical replication or causal effects.

Usage

plot_fingerprints(
  data,
  response = "permittivity",
  title = "Descriptive dielectric frequency-response curves",
  subtitle = "Descriptive measurements; experimental independence must be verified",
  show_legend = TRUE
)

Arguments

Value

A ggplot object.

Examples

# Fully synthetic values, not experimental observations.
x <- expand.grid(
  material = c('Water A', 'Water B'),
  age_hours = c(0, 24),
  frequency_hz = c(10, 100, 1000, 10000)
)
x$permittivity <- 80 -
  4 * log10(x$frequency_hz) -
  0.1 * x$age_hours -
  ifelse(x$material == 'Water B', 3, 0)

plot_fingerprints(
  x,
  response = 'permittivity',
  title = 'Synthetic dielectric responses',
  subtitle = 'Illustrative data only'
)

Import dielectric measurements from an Excel workbook

Description

Supports standard column names, explicit header mappings, and the two original positional worksheet layouts. No experimental classifications or physical sample IDs are inferred.

Usage

read_dielectric(
  path,
  sheet = NULL,
  column_map = NULL,
  layout = c("auto", "standard", "legacy")
)

Arguments

Details

Standard imports require material, age_hours, frequency_hz, permittivity, dissipation_factor, and impedance. Optional columns include fuel, water, concentration_pct and sample_id. Additional columns are retained in standard imports. Frequencies must already be expressed in Hz and ages in hours; renaming columns does not convert units. Analysis functions may require additional classification columns. The COded legacy layout does not supply fuel or water labels.

Value

A data frame with standardised column names.

Examples

path <- system.file('extdata', 'synthetic_import.xlsx',
                    package = 'DielectricWaterR')
x <- read_dielectric(path, sheet = 'Measurements', layout = 'standard')
head(x)

Split measurements by verified experimental unit

Description

Keeps every observation belonging to the same physical experimental unit in either training or testing data. Identifiers must be supplied and independently verified. This function cannot verify physical sample provenance.

Usage

split_by_experimental_unit(data, unit_id, train_prop = 0.8, seed = NULL)

Arguments

Value

List containing training data, testing data, and a summary of the split.

Summarise dielectric frequency-response curves

Description

Calculates descriptive curve features using the trapezoidal rule over log10(frequency). Curves are defined by material and ageing time. These summaries do not establish independent replication.

Usage

summarise_dielectric_curves(data, outcome = "permittivity")

Arguments

Value

A data frame containing curve-level summaries.

Summarise dielectric measurements without assuming independence

Description

Calculates descriptive statistics within experimental conditions. Standard errors and confidence intervals are deliberately not calculated because physical sample independence is not established.

Usage

summarise_dielectric_variability(
  data,
  outcome = "permittivity",
  group_vars = c("fuel", "water", "concentration_pct", "age_hours")
)

Arguments

Value

A data frame of descriptive summaries.