| Title: | Auditing and Exploring Dielectric Measurements of Water |
|---|---|
| Description: | Imports, audits, compares and visualises dielectric measurements of water under fuel contamination and ageing. Provides descriptive summaries, frequency-response comparisons, confidence intervals based on physical-unit means, and training and testing splits that keep observations from the same experimental unit together. Experimental-unit safeguards address pseudoreplication concerns discussed by Hurlbert (1984) <doi:10.2307/1942661>. Grouped splitting is consistent with the structured-data validation principles discussed by Roberts et al. (2017) <doi:10.1111/ecog.02881>. Student t confidence intervals use the standard mean-interval formula described in the NIST/SEMATECH e-Handbook of Statistical Methods <https://www.itl.nist.gov/div898/handbook/eda/section3/eda352.htm>. Experimental-unit identifiers are supplied by the user and are not inferred from material labels. This research prototype does not provide validated contaminant prediction or causal inference. |
| Authors: | Muhammad Zahir Khan [aut, cre], Luqman Abidoye [aut] |
| Maintainer: | Muhammad Zahir Khan <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 0.2.0 |
| Built: | 2026-11-06 21:09:42 UTC |
| Source: | https://github.com/cran/DielectricWaterR |
Summarises dielectric responses across ageing times at a fixed frequency and within the same material. Does not assume repeated measurements of one physical sample.
analyse_ageing_trajectories( data, outcome = "permittivity", frequency_hz, material = NULL )analyse_ageing_trajectories( data, outcome = "permittivity", frequency_hz, material = NULL )
data |
Dielectric measurement data frame. |
outcome |
Numeric dielectric response column. |
frequency_hz |
Frequency to analyse. |
material |
Optional material label to select. |
Data frame containing ageing time, mean response, number of measurements and descriptive changes.
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.
analyse_frequency_response(data, min_frequencies = 5L)analyse_frequency_response(data, min_frequencies = 5L)
data |
A dielectric dataset returned by read_dielectric(). |
min_frequencies |
Minimum distinct frequencies per curve. |
A tibble containing descriptive curve summaries.
Audit dielectric data without inventing physical sample IDs
audit_dielectric(data)audit_dielectric(data)
data |
Output from read_dielectric(). |
List containing summary, missingness, ranges, duplicated keys and warnings.
Summarises measurements by material label and reports whether physical sample identities can be established. Material names are not assumed to identify physical samples.
audit_experimental_units(data, sample_id = NULL)audit_experimental_units(data, sample_id = NULL)
data |
A dielectric measurement data frame. |
sample_id |
Optional column name containing genuine physical sample identifiers. |
A data frame summarising material labels, ageing times, frequencies and sample identity status.
# 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')# 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')
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.
audit_frequency_exclusions(data)audit_frequency_exclusions(data)
data |
A dielectric dataset returned by read_dielectric(). |
A data frame containing the original observations, their row identifiers, expected water codes, medium-label status, and analysis inclusion decisions.
Matches measurements by fuel, water medium, concentration and frequency. Returns descriptive ratios between two ageing times. Ratios do not establish causal effects.
compare_ageing(data, age_start, age_end)compare_ageing(data, age_start, age_end)
data |
A dielectric measurement data frame. |
age_start |
Starting ageing time in hours. |
age_end |
Ending ageing time in hours. |
A data frame containing matched measurements and ratios for permittivity, dissipation factor and impedance.
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.
compare_common_frequency_curves(data, outcome = "permittivity")compare_common_frequency_curves(data, outcome = "permittivity")
data |
Dielectric measurement data frame. |
outcome |
Numeric response column name. |
A list with shared frequencies, aligned responses, and curve-level AUC summaries when possible.
Compare petrol and diesel at identical experimental conditions using descriptive response ratios.
compare_dielectric_fingerprints( data, response = "permittivity", age_hours = 0, max_concentration = 20, exclude_conflicts = TRUE )compare_dielectric_fingerprints( data, response = "permittivity", age_hours = 0, max_concentration = 20, exclude_conflicts = TRUE )
data |
Data returned by read_dielectric(). |
response |
One of permittivity, dissipation_factor, or impedance. |
age_hours |
Measurement age in hours. |
max_concentration |
Maximum concentration percentage. |
exclude_conflicts |
Exclude water-code mismatches. |
A list containing matched results, summary, and duplicate-condition diagnostics.
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.
estimate_dielectric_ci( data, outcome = "permittivity", sample_id, conf_level = 0.95 )estimate_dielectric_ci( data, outcome = "permittivity", sample_id, conf_level = 0.95 )
data |
A data frame containing dielectric measurements. |
outcome |
Numeric outcome column name. |
sample_id |
Column identifying independent physical units. |
conf_level |
Confidence level between zero and one. |
One-row data frame containing the mean, interval, and number of independent physical units.
Calculates descriptive prediction errors. Does not establish external-data independence.
evaluate_external_predictions(observed, predicted)evaluate_external_predictions(observed, predicted)
observed |
Numeric observed responses. |
predicted |
Numeric predicted responses. |
One-row data frame with n, MAE, RMSE and bias.
Produces descriptive frequency-response curves by material and recorded ageing time. Curves do not establish independent physical replication or causal effects.
plot_fingerprints( data, response = "permittivity", title = "Descriptive dielectric frequency-response curves", subtitle = "Descriptive measurements; experimental independence must be verified", show_legend = TRUE )plot_fingerprints( data, response = "permittivity", title = "Descriptive dielectric frequency-response curves", subtitle = "Descriptive measurements; experimental independence must be verified", show_legend = TRUE )
data |
Data frame containing dielectric measurements. |
response |
One of permittivity, dissipation_factor, impedance. |
title |
Optional plot title. |
subtitle |
Optional plot subtitle. |
show_legend |
Whether to display material and ageing legends. |
A ggplot object.
# 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' )# 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' )
Supports standard column names, explicit header mappings, and the two original positional worksheet layouts. No experimental classifications or physical sample IDs are inferred.
read_dielectric( path, sheet = NULL, column_map = NULL, layout = c("auto", "standard", "legacy") )read_dielectric( path, sheet = NULL, column_map = NULL, layout = c("auto", "standard", "legacy") )
path |
Path to an Excel workbook. |
sheet |
Worksheet name or index. NULL selects All extract_mean when present, otherwise the first worksheet. |
column_map |
Named character vector mapping standard column names to workbook headers, for example c(frequency_hz = 'Frequency', permittivity = 'Epsilon'). |
layout |
One of auto, standard, or legacy. Auto first accepts standard headers, then falls back to known legacy sheet layouts. |
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.
A data frame with standardised column names.
path <- system.file('extdata', 'synthetic_import.xlsx', package = 'DielectricWaterR') x <- read_dielectric(path, sheet = 'Measurements', layout = 'standard') head(x)path <- system.file('extdata', 'synthetic_import.xlsx', package = 'DielectricWaterR') x <- read_dielectric(path, sheet = 'Measurements', layout = 'standard') head(x)
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.
split_by_experimental_unit(data, unit_id, train_prop = 0.8, seed = NULL)split_by_experimental_unit(data, unit_id, train_prop = 0.8, seed = NULL)
data |
Data frame containing measurements. |
unit_id |
Name of verified experimental-unit column. |
train_prop |
Proportion of unique units for training. |
seed |
Optional non-negative integer seed. NULL uses and advances the caller's random-number state. An explicit seed gives reproducible results and restores the caller's random-number state. |
List containing training data, testing data, and a summary of the split.
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.
summarise_dielectric_curves(data, outcome = "permittivity")summarise_dielectric_curves(data, outcome = "permittivity")
data |
Dielectric measurement data frame. |
outcome |
Name of a numeric response column. |
A data frame containing curve-level summaries.
Calculates descriptive statistics within experimental conditions. Standard errors and confidence intervals are deliberately not calculated because physical sample independence is not established.
summarise_dielectric_variability( data, outcome = "permittivity", group_vars = c("fuel", "water", "concentration_pct", "age_hours") )summarise_dielectric_variability( data, outcome = "permittivity", group_vars = c("fuel", "water", "concentration_pct", "age_hours") )
data |
A dielectric measurement data frame. |
outcome |
Name of a numeric outcome column. |
group_vars |
Names of grouping columns. |
A data frame of descriptive summaries.