Package 'HLCtools'

Calculate interval-level Herd Lying Concordance

Description

Calculates Herd Lying Concordance (HLC) metrics from individual animal lying-time records. HLC is calculated within each group-time interval as one minus a normalised measure of between-animal dispersion.

Usage

calculate_hlc(
  data,
  group,
  animal,
  interval,
  lying,
  day = NULL,
  period = NULL,
  interval_min = 15,
  methods = c("sd", "mad", "iqr", "entropy"),
  lying_threshold = interval_min/2,
  sync_thresholds = c(0.6, 0.7, 0.8, 0.9),
  add_lying_weighted = TRUE
)

Arguments

data	A data frame containing individual animal behaviour records.
group	Column identifying the herd, treatment, pen, or group.
animal	Column identifying the individual animal.
interval	Column identifying the time interval within day.
lying	Column containing lying time within the interval, in minutes.
day	Optional column identifying day/date.
period	Optional column identifying a larger period, for example week.
interval_min	Length of the observation interval in minutes. Default is 15.
methods	Character vector of HLC methods to compute. Options are "sd", "mad", "iqr", and "entropy".
lying_threshold	Threshold in minutes used to define binary lying state for entropy. Default is half of interval_min.
sync_thresholds	Numeric vector of threshold synchrony cut-offs, expressed as proportions. Default is c(0.6, 0.7, 0.8, 0.9).
add_lying_weighted	Logical. If TRUE, adds lying-weighted HLC metrics.

Value

A tibble with one row per group-time interval.

Examples

data(example_lies)

hlc_intervals <- calculate_hlc(
  data = example_lies,
  group = group,
  animal = cow,
  day = day,
  period = week,
  interval = time,
  lying = lying,
  interval_min = 15,
  methods = c("sd", "mad", "iqr", "entropy"),
  sync_thresholds = c(0.6, 0.7, 0.8, 0.9),
  add_lying_weighted = TRUE
)

hlc_intervals

---

Compare HLC methods

Description

Summarises HLC metrics across available dispersion bases. This function helps users compare HLC implementations rather than automatically selecting a single best metric.

Usage

compare_hlc_methods(data, metrics = NULL)

Arguments

data	A data frame containing HLC summary columns. This can be daily, weekly, treatment-level, or another summarised object.
metrics	Optional character vector of HLC columns to compare. If NULL, columns matching mean_HLC_SD, mean_HLC_MAD, mean_HLC_IQR, mean_HLC_ENT, HLC_SD, HLC_MAD, HLC_IQR, and HLC_ENT are used when available.

Value

A tibble with descriptive summaries for each available HLC method.

Examples

data(example_lies)

hlc_intervals <- calculate_hlc(
  data = example_lies,
  group = group,
  animal = cow,
  day = day,
  period = week,
  interval = time,
  lying = lying
)

hlc_daily <- summarise_hlc_daily(
  data = hlc_intervals,
  group = group,
  day = day,
  period = week
)

compare_hlc_methods(hlc_daily)

---

Example lying behaviour dataset

Description

A small synthetic dataset for demonstrating Herd Lying Concordance calculations. The dataset contains individual animal lying times for two groups, two days, two time intervals per day, and five cows per group-time interval.

Usage

example_lies

Format

A data frame with 40 rows and 6 columns:

group

Group identifier.

day

Day identifier.

week

Week identifier.

time

Time interval identifier.

cow

Individual cow identifier.

lying

Lying time within the interval, in minutes.

Examples

data(example_lies)

hlc_intervals <- calculate_hlc(
  data = example_lies,
  group = group,
  animal = cow,
  day = day,
  period = week,
  interval = time,
  lying = lying
)

hlc_intervals

---

List available unweighted HLC methods

Description

Returns the currently implemented unweighted Herd Lying Concordance dispersion bases.

Usage

hlc_methods()

Value

A character vector of available unweighted method names.

---

List available lying-weighted HLC methods

Description

Returns the names of the currently implemented lying-weighted Herd Lying Concordance methods.

Usage

hlc_weighted_methods()

Value

A character vector containing the available lying-weighted HLC method names.

Examples

hlc_weighted_methods()

---

Rank HLC methods for a dataset

Description

Ranks available Herd Lying Concordance (HLC) implementations using descriptive criteria relevant for method selection. The function supports daily, weekly, treatment-level, or other summarised HLC outputs.

Usage

rank_hlc_methods(
  data,
  group = NULL,
  period = NULL,
  lying_prop = NULL,
  metrics = NULL,
  weights = c(detectability = 1, temporal_stability = 1, outlier_robustness = 1, boundary
    = 1, missingness = 1, degeneracy = 1)
)

Arguments

data	A data frame containing HLC summary columns.
group	Optional column identifying treatment, herd, pen, farm, or another comparison group. If supplied, group detectability is evaluated.
period	Optional column identifying week, period, block, or another temporal unit. If supplied, temporal stability is evaluated.
lying_prop	Optional column containing lying proportion. If supplied, Spearman correlation between each HLC method and lying proportion is reported.
metrics	Optional character vector of HLC columns to rank. If NULL, columns matching mean_HLC_SD, mean_HLC_MAD, mean_HLC_IQR, mean_HLC_ENT, HLC_SD, HLC_MAD, HLC_IQR, and HLC_ENT are used when available.
weights	Named numeric vector giving weights for ranking criteria. Supported names are "detectability", "temporal_stability", "outlier_robustness", "boundary", "missingness", and "degeneracy".

Details

The ranking is intended to support transparent, dataset-specific selection of an HLC implementation. It does not imply that one dispersion basis is universally best.

Ranking criteria:

• detectability: group separation, based on an F statistic from nested linear models when group is supplied.

• temporal_stability: SD of period-level means when period is supplied.

• outlier_robustness: absolute distance of SD/MAD from 1.

• boundary: percentage of exact 0 or 1 values.

• missingness: percentage of missing values.

• degeneracy: penalises metrics with zero variance or very high boundary collapse.

Criteria that cannot be evaluated because the required columns were not supplied are omitted from the weighted score. Metrics with missing values for an otherwise available criterion are ranked last for that criterion.

Value

A tibble summarising method performance and ranking. Lower weighted_rank_score indicates a more favourable method under the chosen criteria. The column selected marks the top-ranked method.

Examples

data(example_lies)

hlc_intervals <- calculate_hlc(
  data = example_lies,
  group = group,
  animal = cow,
  day = day,
  period = week,
  interval = time,
  lying = lying
)

hlc_daily <- summarise_hlc_daily(
  data = hlc_intervals,
  group = group,
  day = day,
  period = week
)

rank_hlc_methods(
  data = hlc_daily,
  group = group,
  period = week,
  lying_prop = mean_lying_prop
)

---

Summarise HLC metrics by day

Description

Aggregates interval-level HLC metrics into daily group-level summaries.

Usage

summarise_hlc_daily(data, group, day, period = NULL, interval_min = 15)

Arguments

data	Interval-level HLC data produced by calculate_hlc().
group	Column identifying herd, treatment, pen, or group.
day	Column identifying day/date.
period	Optional column identifying a larger period, for example week.
interval_min	Length of the observation interval in minutes. Default is 15.

Value

A tibble with daily HLC summaries.

Examples

data(example_lies)

hlc_intervals <- calculate_hlc(
  data = example_lies,
  group = group,
  animal = cow,
  day = day,
  period = week,
  interval = time,
  lying = lying,
  interval_min = 15
)

hlc_daily <- summarise_hlc_daily(
  data = hlc_intervals,
  group = group,
  day = day,
  period = week,
  interval_min = 15
)

hlc_daily

---