Package 'greenfeedr'

Download Preliminary and Raw 'GreenFeed' Data via 'API'

Description

Downloads preliminary and raw 'GreenFeed' data from the 'C-Lock Inc.' server via an 'API'. Retrieves data based on specified parameters (login, date range, and units), and provides a CSV file with the 'GreenFeed' preliminary data.

Usage

get_gfdata(
  user,
  pass,
  d = "visits",
  type = 2,
  exp = NA,
  unit,
  start_date,
  end_date = Sys.Date(),
  save_dir = tempdir()
)

Arguments

user	a character string representing the user name to logging into 'GreenFeed' system
pass	a character string representing password to logging into 'GreenFeed' system
d	a character string representing data to download (opts: "visits", "feed", "rfid", "cmds")
type	a numeric representing the type of data to retrieve (1=finalized and 2=preliminary)
exp	a character string representing study name or other study identifier. It is used as file name to save the data
unit	numeric or character vector, or a list representing one or more 'GreenFeed' unit numbers
start_date	a character string representing the start date of the study (format: "DD-MM-YY" or "YYYY-MM-DD")
end_date	a character string representing the end date of the study (format: "DD-MM-YY" or "YYYY-MM-DD")
save_dir	a character string representing the directory to save the output file

Value

A CSV file with the specified data (visits or raw) saved in the provided directory.

Examples

# Please replace "your_username" and "your_password" with your actual 'GreenFeed' credentials.
# By default, the function downloads the preliminary 'GreenFeed' data,
# if raw data is needed use options: "feed", "rfid", or "cmds"

get_gfdata(
  user = "your_username",
  pass = "your_password",
  d = "visits",
  type = 2,
  exp = "StudyName",
  unit = c(304, 305),
  start_date = "2024-01-01",
  end_date = Sys.Date(),
  save_dir = tempdir()
)

---

Process 'GreenFeed' Pellet Intakes

Description

Processes 'feedtimes' file from 'GreenFeed' system. Food drops are used to calculate pellet intakes per animal. Aggregates data to provide insights into the feeding behavior and pellet consumption of the animals during a study.

Arguments

user	a character string representing the user name to logging into 'GreenFeed' system
pass	a character string representing password to logging into 'GreenFeed' system
unit	numeric or character vector or list representing one or more 'GreenFeed' unit numbers. The order should match with "feedtimes" files
gcup	a numeric value representing the grams of pellets per cup. If dual-hopper you can define multiple grams per unit
start_date	a character string representing the start date of the study (format: "DD-MM-YY" or "YYYY-MM-DD")
end_date	a character string representing the end date of the study (format: "DD-MM-YY" or "YYYY-MM-DD")
save_dir	a character string representing the directory to save the output file
rfid_file	a character string representing the file with individual IDs. The order should be Visual ID (col1) and RFID (col2)
file_path	a character string or list representing files(s) with "feedtimes" from 'C-Lock Inc.'

Value

An Excel file with pellet intakes for all animals and days within the specified period is saved to save_dir. The file is named "Pellet_Intakes_YYYY-MM-DD_YYYY-MM-DD.csv".

Examples

# You should provide the 'feedtimes' file provided by C-Lock.
# it could be a list of files if you have data from multiple units to combine
path <- system.file("extdata", "feedtimes.csv", package = "greenfeedr")

# You must include the grams of pellets per cup based on the result obtained from the 10-drops test

# If the user include an rfid file, the structure should be in col1 AnimalName or Visual ID, and
# col2 the RFID or TAG_ID. The file could be save in different formats (.xlsx, .csv, or .txt).
RFIDs <- system.file("extdata", "RFID_file.csv", package = "greenfeedr")

pellin(
  unit = 1,
  gcup = 34,
  start_date = "2024-05-13",
  end_date = "2024-05-25",
  save_dir = tempdir(),
  rfid_file = RFIDs,
  file_path = path
)

---

Process Preliminary and Finalized 'GreenFeed' Data

Description

Processes and calculates daily, weekly, and experimental averages of 'GreenFeed' data.

When param1, param2, and min_time are all omitted (the default), the function automatically selects the combination of filtering parameters that minimises the median relative standard error (RSE) of individual animal emission estimates while retaining at least min_retention of the study animals. For each animal, RSE equals $(SD_{weekly} / \bar{x}) / \sqrt{n_{weeks}} \times 100$, directly measuring how precisely the repeated spot-sample means converge on the animal's true emission rate. Because RSE is computed entirely from the data, the optimal parameters are study-specific — no external thresholds are imposed. Diurnal time bins are derived from the data and used in the optimisation. The selected parameters are printed to the console, and the full optimisation table is attached as attr(result, "optimization").

When all three of param1, param2, and min_time are supplied, the function runs in manual mode with those exact values.

Arguments

data	a data frame with preliminary or finalized 'GreenFeed' data.
start_date	character. Start date ("DD-MM-YY" or "YYYY-MM-DD").
end_date	character. End date ("DD-MM-YY" or "YYYY-MM-DD").
param1	integer. Minimum records per day. Omit for automatic selection (default: NULL).
param2	integer. Minimum days with records per week. Omit for automatic selection (default: NULL).
min_time	numeric. Minimum visit duration in minutes. Omit for automatic selection (default: NULL).
gas	character. Gas used for reliability optimisation in automatic mode. One of "CH4", "CO2", "O2", "H2". Default: "CH4".
min_retention	numeric (0–1). Minimum proportion of study animals a combination must retain in automatic mode. Default: 0.80.
tol	numeric. Combinations within tol percentage points of the minimum median RSE are treated as tied; the most lenient is selected. Default: 0.5.
quick	logical. Use a reduced parameter grid in automatic mode. Default: FALSE.
peak_hour	optional integer. Hour of peak emissions for bin-weighted daily means (manual mode only; auto-detected in automatic mode).
trough_hour	optional integer. Hour of trough emissions for bin-weighted daily means (manual mode only).
min_bins	integer (1 or 2). Minimum diurnal phases an animal-day must cover to be retained. Optimised automatically in auto mode; default 1 in manual mode.
min_weeks_pct	numeric (0–1). Minimum proportion of study weeks in which an animal must have valid weekly records to be included in the experimental averages (exp_data). Default: 0.50.
transform	logical. Convert gas production from g/day to L/day. Default: FALSE.
cutoff	integer. SDs for outlier removal. Default: 3.

Value

A named list with four data frames:

filtered_data	visit-level records after quality filtering.
daily_data	daily emission estimates.
weekly_data	weekly emission estimates.
exp_data	one row per animal: experimental mean across weeks, with columns RFID, weeks, days, totaln, minutes, and one column per gas. Only animals present in at least min_weeks_pct of study weeks are included.

In automatic mode, the full optimisation table (column med_rse: median relative SE in percent) is accessible via attr(result, "optimization") and the diurnal analysis via attr(result, "diurnal").

Examples

file <- system.file("extdata", "StudyName_GFdata.csv", package = "greenfeedr")
datafile <- readr::read_csv(file)

# Automatic mode (recommended)
gf <- process_gfdata(datafile, "2024-05-13", "2024-05-25")
attr(gf, "optimization")   # full grid results
attr(gf, "diurnal")$plot   # diurnal curve

# Manual mode
gf <- process_gfdata(datafile, "2024-05-13", "2024-05-25",
                     param1 = 2, param2 = 3, min_time = 2)

---

Download and Report 'GreenFeed' Data

Description

Generates a PDF report of preliminary and finalized 'GreenFeed' data. The report includes: number of animals using 'GreenFeed' and plots with distribution of records and gas production. If the preliminary option is used, the data is retrieved from the 'C-Lock Inc.' server through an 'API', otherwise the data processed by 'C-Lock Inc.' must be provided to generate the report.

Arguments

input_type	a character string representing type of data (options: "preliminary" and "finalized")
exp	a character string representing study name or other study identifier. It is used as file name to save the data
unit	numeric or character vector, or a list representing one or more 'GreenFeed' unit numbers
start_date	a character string representing the start date of the study (format: "DD-MM-YY" or "YYYY-MM-DD")
end_date	a character string representing the end date of the study (format: "DD-MM-YY" or "YYYY-MM-DD")
save_dir	a character string representing the directory to save the output file
plot_opt	a character string representing the gas(es) to plot (options: "All", "CH4", "CO2", "O2", "H2")
rfid_file	a character string representing the file with individual IDs. The order should be Visual ID (col1) and RFID (col2)
user	a character string representing the user name to logging into 'GreenFeed' system. If input_type is "final", this parameter is ignored
pass	a character string representing password to logging into 'GreenFeed' system. If input_type is "final", this parameter is ignored
file_path	A list of file paths containing the final report(s) from the 'GreenFeed' system. If input_type is "prelim", this parameter is ignored

Value

A CSV file with preliminary 'GreenFeed' data and a PDF report with a description of the preliminary or finalized data

Examples

# Please replace "your_username" and "your_password" with your actual 'GreenFeed' credentials.
# The data range must be fewer than 180 days
# Example without rfid_file (by default NA)

report_gfdata(
  user = "your_username",
  pass = "your_password",
  input_type = "preliminary",
  exp = "StudyName",
  unit = 1,
  start_date = "2023-01-01",
  end_date = Sys.Date(),
  save_dir = tempdir(),
  plot_opt = "All"
)

---

Run the 'greenfeedr' Shiny App locally

Description

Launches the 'greenfeedr' Shiny application on your computer. The app provides an interactive interface for 'GreenFeed' data analysis, visualization, and reporting.

Usage

run_gfapp()

Value

This function launches the Shiny app in your default web browser; it does not return a value.

Examples

## Not run: 
  greenfeedr::run_gfapp()

## End(Not run)

---

Process 'GreenFeed' Visits

Description

Processes 'GreenFeed' visits and food drops for a requested period. Generates a list of animals not visiting the 'GreenFeed' to manage them, and a description of animals visiting the 'GreenFeed'.

Arguments

user	a character string representing the user name to logging into 'GreenFeed' system
pass	a character string representing password to logging into 'GreenFeed' system
unit	numeric or character vector or list representing one or more GreenFeed unit numbers.
start_date	a character string representing the start date of the study (format: "DD-MM-YY" or "YYYY-MM-DD")
end_date	a character string representing the end date of the study (format: "DD-MM-YY" or "YYYY-MM-DD")
rfid_file	a character string representing the file with individual RFIDs. The order should be Visual ID (col1) and RFID (col2)
file_path	a character string or list representing files(s) with feedtimes from 'C-Lock Inc.'

Value

A list of two data frames:

visits_per_day	Data frame with daily processed 'GreenFeed' data, including columns for VisualID, Date, Time, number of drops, and visits.
visits_per_animal	Data frame with weekly processed 'GreenFeed' data, including columns for VisualID, total drops, total visits, mean drops, and mean visits.

Examples

# You should provide the feedtimes files.
# it could be a list of files if you have data from multiple units to combine
path <- system.file("extdata", "feedtimes.csv", package = "greenfeedr")

# If the user include an rfid file, the structure should be in col1 AnimalName or VisualID, and
# col2 the RFID or TAG_ID. The file could be save in different formats (.xlsx, .csv, or .txt).
RFIDs <- system.file("extdata", "RFID_file.csv", package = "greenfeedr")

data <- viseat(
  file_path = path,
  unit = 1,
  start_date = "2024-05-13",
  end_date = "2024-05-25",
  rfid_file = RFIDs
)

---