% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/flong.R
\name{f_long}
\alias{f_long}
\title{Transform 'Wide' (Excel) data to 'Long' (R) format}
\usage{
f_long(
  data,
  measure_columns = NULL,
  keep_cols = NULL,
  category_name = "name",
  value_name = "value",
  category_labels = NULL,
  ...
)
}
\arguments{
\item{data}{The input data frame (e.g., from \code{read_excel}).}

\item{measure_columns}{(Optional) The columns containing your numeric measurements.
These values are often the response variables, i.e. will end up on the Y-axis.
\itemize{
  \item Use column names: \code{c("OD_t0", "OD_t1")}
  \item Use column numbers: \code{2:5}
  \item Use helpers: \code{starts_with("Measure")}
}
If NULL (default), the function will pivot ALL columns except those in \code{keep_cols}.}

\item{keep_cols}{(Optional) The columns that identify your samples (IDs).
E.g., "SampleID", "PatientID", "Treatment", "Student number".
These are repeated for every measurement.
*If left empty, all non-measured columns are kept.*
Important: If \code{measure_columns} is NULL, you MUST specify \code{keep_cols}.}

\item{category_name}{Name for the new column containing the headers.
Default is "name". Choose something logical like "Timepoints", "Genes", or "Condition".}

\item{value_name}{Name for the new column containing the numbers.
Default is "value". Choose something logical like "Absorbance", "Ct_Value", or "Weight".}

\item{category_labels}{(Optional) A character vector of new, readable names for your categories, i.e. the measure_columns that you entered.
\strong{Note:} The order must match the order of \code{measure_columns} exactly.
Useful for renaming "t0_raw" to "Start" instantly.}

\item{...}{Additional arguments passed to \code{tidyr::pivot_longer}.
E.g., \code{values_drop_na = TRUE} to remove empty cells immediately.}
}
\value{
A "Tidy" data frame (tibble) of class \code{f_long}.
}
\description{
This function converts "wide" data (e.g. Excel tables) into a "long" list format.
This is the essential first step to prepare your data for analysis and plotting in R.
}
\details{
Research data in Excel or output from lab instruments often contains measurements
side-by-side (in columns). Many R functions require measurements in a single
column (rows). `f_long` performs this translation for you.

It performs three actions in one go:
1. Selects your measurement columns (`measure_columns`).
2. Keeps your important ID columns (`keep_cols`) and removes the rest.
3. (Optional) Renames cryptic column headers into readable labels (`category_labels`).
}
\note{
The custom class and attributes (\code{f_long_value}, \code{f_long_category})
  are used by the \code{plot} and \code{summary} methods. Be aware that most
  \pkg{dplyr} or \pkg{tidyr} operations (e.g., \code{filter}, \code{mutate})
  will silently strip these attributes. If that happens, use \code{f_scan} or
  \code{f_summary} directly with explicit column names instead.
}
\examples{
# --- Example 1: Using the 'iris' dataset ---
# Scenario: The iris dataset looks clean, but it is actually "Wide".
# It has 4 columns of measurements side-by-side.
# To compare Sepal Length vs Width in a plot, we must stack them.

head(iris)

# Reshape: Combine Length and Width into one column and plot the data.
iris_long <- f_long(
  data = iris,
  measure_columns = c("Sepal.Length", "Sepal.Width"),
  keep_cols = "Species",
  category_name = "Sepal_Dimension",    # Describes the grouping (What did we measure?)
  value_name = "Size_cm",               # Describes the value (What is the number?)
  category_labels=c("Length", "Width")  # New category labels
  )

 head(iris_long)

 # Plot the data using f_scan
 plot(iris_long)

 # Make a f_summary table of iris_long
 summary(iris_long)

# --- Example 2: Using the 'airquality' dataset ---
# Scenario: Pivot daily measurements of Wind and Temperature over time.

head(airquality)

weather_long <- f_long(
  data = airquality,
  measure_columns = c("Wind", "Temp"),
  keep_cols = c("Month", "Day"),
  category_name = "Climate_Parameter", # Descriptive name
  value_name = "Reading_Value",        # Generic name (since units differ: mph vs F)
  values_drop_na = TRUE
)

head(weather_long)
}
