% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/read_messy_panel.R
\name{read_messy_panel}
\alias{read_messy_panel}
\title{Robust Parsing and Extraction of Messy Excel Panel Data}
\usage{
read_messy_panel(
  file_path,
  sheet = NULL,
  na_strings = c("", "NA", "#N/A", "NULL", "S", "D", "ND", "N/A", "*", "**", "***", ".",
    "x", "c", "s", "z", "#VALUE!", "#REF!", "#DIV/0!", "#NUM!", "#NAME?", "none", "NR",
    "--", "---", "n.a.", "N.A.", "n/a", "Not Applicable"),
  clean_vars = TRUE,
  auto_pivot = FALSE,
  return_audit = FALSE
)
}
\arguments{
\item{file_path}{Character string. Path to the Excel file.}

\item{sheet}{Optional sheet name or index. If \code{NULL} (the default), it auto-discovers the first valid data panel across all sheets. If \code{"ALL"}, parses and merges all sheets.}

\item{na_strings}{Character vector. Strings to interpret as missing values. Supports complex missing-value lexicons.}

\item{clean_vars}{Logical. If \code{TRUE} (default), standardizes variable names to snake_case using \code{clean_variable_names()}.}

\item{auto_pivot}{Logical. If \code{TRUE}, attempts to reshape wide temporal columns (e.g., FY2021, Q1_2022) into a long format (\code{time_period}, \code{value}).}

\item{return_audit}{Logical. If \code{TRUE}, returns a list containing \verb{$data} (the cleaned data frame) and \verb{$audit} (a detailed log of all algorithmic modifications made).}
}
\value{
If \code{return_audit = FALSE}, a cleaned and standardized \code{data.frame}.
If \code{return_audit = TRUE}, a named list containing:
\item{data}{The cleaned \code{data.frame}.}
\item{audit}{A \code{data.frame} detailing exactly what transformations, truncations, or imputations were applied.}
}
\description{
\code{read_messy_panel()} is an industrial-grade parser designed to extract clean, standardized data frames
from heavily malformed, human-readable Excel reports (e.g., financial statements, ERP exports).
It automatically bypasses decoy rows, stitches N-dimensional hierarchical headers, extracts structural
indentation hierarchies (parent-child relationships), amputates embedded subtotals, and standardizes
financial/scientific numbers.
}
\examples{
# Toy example: create a small in-memory Excel file and parse it
tmp <- tempfile(fileext = ".xlsx")
df_raw <- data.frame(
  Category = c("Revenue", "Cost", "Total"),
  `2022` = c("1.2M", "800k", "2.0M"),
  `2023` = c("1.5M", "900k", "2.4M"),
  check.names = FALSE
)
writexl::write_xlsx(df_raw, tmp)
result <- read_messy_panel(tmp, auto_pivot = TRUE)
head(result)
unlink(tmp)

}
