% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/merge_dataset.R
\name{merge_dataset}
\alias{merge_dataset}
\title{Merge Two Trait Datasets by Species}
\usage{
merge_dataset(main_data, additional_data, priority = "main")
}
\arguments{
\item{main_data}{A data frame containing the primary dataset. It must
include a `"species"` column containing non-missing, non-empty species
names.}

\item{additional_data}{A data frame containing the additional dataset. It
must include a `"species"` column containing non-missing, non-empty
species names.}

\item{priority}{Character string specifying how overlapping non-missing
values are resolved. Available options are:
\itemize{
  \item `"main"` retains the value from `main_data`. This is the default.
  \item `"additional"` retains the value from `additional_data`.
  \item `"mean"` uses the arithmetic mean of the two values when the
    corresponding columns in both datasets are numeric. For non-numeric
    columns, it retains the value from `main_data`.
}}
}
\value{
A data frame containing all unique species and all variables present
  in either input dataset. The `"species"` column is placed first. Species
  retain their order from `main_data`, followed by species occurring only
  in `additional_data`. Other columns retain their order from `main_data`,
  followed by columns occurring only in `additional_data`.
}
\description{
`merge_dataset()` combines two species-level trait datasets using the
`"species"` column as the matching key. Species and variables occurring in
either dataset are retained, and overlapping values are resolved using a
user-selected priority rule.
}
\details{
Species names are matched exactly. The function does not standardize
taxonomic names, spelling, capitalization, or synonyms.

Each input dataset is expected to contain no more than one row per species.
If duplicate species are present, the function issues a warning and uses
only the first occurrence of each species in that dataset.

All columns other than `"species"` are merged using the selected priority
rule, including trait variables and taxonomic metadata such as genus or
family.

For a given species and variable, a non-missing value is retained when the
corresponding value in the other dataset is missing. The selected priority
rule is used only when both datasets contain non-missing values.

With `priority = "mean"`, averaging is performed only when the corresponding
columns in both datasets are numeric. The two source values receive equal
weight. When either value is missing, the available value is retained.
For non-numeric columns, `priority = "mean"` has the same effect as
`priority = "main"`.

Factor columns are converted to character columns before merging. Variable
names should be unique within each input dataset because duplicated column
names are not resolved by the function.
}
\examples{
main_data <- data.frame(
  species = c("Species a", "Species b"),
  genus = c("Genus1", "Genus2"),
  Trait1 = c(1, NA),
  Trait2 = c(4, 6)
)

additional_data <- data.frame(
  species = c("Species a", "Species c"),
  genus = c("Genus1", "Genus3"),
  Trait1 = c(3, 5),
  Trait3 = c(8, 9)
)

# Prioritize values from the main dataset
merge_dataset(
  main_data,
  additional_data
)

# Average overlapping numeric values
merge_dataset(
  main_data,
  additional_data,
  priority = "mean"
)

}
