% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/download_data_huggingface.R
\name{download_data_huggingface}
\alias{download_data_huggingface}
\title{Download data from a Hugging Face dataset}
\usage{
download_data_huggingface(
  dataset = NULL,
  start_date = "2007-06-27",
  end_date = "2007-07-27",
  type = deprecated(),
  ...
)
}
\arguments{
\item{dataset}{Character(1). The dataset to download. Supported values are
\code{"high_frequency_sp500"} and \code{"factor_library"}.}

\item{start_date}{Date or character. Start date (inclusive) in
\code{"YYYY-MM-DD"} format. Only used for \code{"high_frequency_sp500"}.}

\item{end_date}{Date or character. End date (inclusive) in \code{"YYYY-MM-DD"}
format. Only used for \code{"high_frequency_sp500"}.}

\item{type}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} Use \code{dataset} instead.}

\item{...}{For \code{dataset = "factor_library"}: named arguments used to filter
the portfolio grid. Each argument takes the form \code{column = value}, where
\code{value} may be a vector to match multiple levels. Optionally pass
\code{fill_all = TRUE} to leave unspecified columns unrestricted (default:
\code{FALSE}, i.e. unspecified columns are fixed at the defaults listed below).
Passing \code{NULL} for any parameter removes that filter entirely, returning
all values for that column (e.g., \code{min_size_quantile = NULL} includes all
size groups). Passing an unrecognised column name raises an error listing
the supported names. Ignored when \code{dataset != "factor_library"}. See the
Details section for supported columns and their defaults.}
}
\value{
A tibble with the downloaded data. For \code{"high_frequency_sp500"},
contains 5-second aggregated orderbook snapshots filtered to the requested
date range. For \code{"factor_library"}, contains portfolio return data joined
with the full grid metadata for the matched portfolio IDs.
}
\description{
Downloads data from a supported Hugging Face dataset. For
\code{"high_frequency_sp500"}, parquet files are filtered by date range and
row-bound. For \code{"factor_library"}, portfolio characteristics are selected via
\code{filter_factor_library_grid()} and the matching return data is downloaded.
}
\details{
\strong{Note on \code{dataset = "factor_library"} defaults:} The defaults below reflect
one common portfolio construction choice, but may not suit every research
question. Always verify that the selected combination matches your intended
design.

Supported columns and their defaults for \code{...}:
\itemize{
\item \code{sorting_variable}: \strong{Required.} The firm characteristic used
to sort stocks into portfolios (e.g., \code{"me"} for market equity,
\code{"bm"} for book-to-market). No default is applied.
\item \code{min_size_quantile} (defaults to \code{0.2}): Fraction of the smallest
stocks (by market cap) excluded from the portfolio universe. \code{0.2}
drops the bottom 20\%.
\item \code{exclude_financials} (defaults to \code{FALSE}): Whether to drop
financial-sector stocks (SIC 6000-6999) from the universe.
\item \code{exclude_utilities} (default: \code{FALSE}): Whether to drop
utility-sector stocks (SIC 4900-4999) from the universe.
\item \code{exclude_negative_earnings} (defaults to \code{FALSE}): Whether to
drop firms with negative earnings before sorting.
\item \code{sorting_variable_lag} (defaults to \code{"6m"}): Lag applied to the
sorting variable before portfolio assignment (e.g., \code{"6m"} = 6-month
lag).
\item \code{rebalancing} (defaults to \code{"monthly"}): How frequently portfolios
are reformed: \code{"monthly"} or \code{"annual"}.
\item \code{n_portfolios_main} (defaults to \code{10}): Number of quantile groups
(e.g., \code{10} for decile portfolios).
\item \code{sorting_method} (defaults to \code{"univariate"}): Whether portfolios
are formed on a single sort (\code{"univariate"}) or a sequential double
sort (\code{"sequential"}).
\item \code{n_portfolios_secondary} (defaults to \code{NULL}): Number of groups
for the secondary sort variable.
Required when \code{sorting_method} is not \code{"univariate"}.
\item \code{breakpoints_exchanges} (defaults to: \code{"NYSE"}): Exchange(s) used
to compute breakpoints. \code{"NYSE"} uses only NYSE-listed stocks to
define quantile cutoffs (the conventional Fama-French approach).
\item \code{breakpoints_min_size_threshold} (defaults to \code{NULL}): Minimum
market-cap threshold (in USD) applied when computing breakpoints.
\code{NULL} means no minimum-size screen is applied.
\item \code{weighting_scheme} (defaults to \code{"VW"}): Return weighting within
portfolios: \code{"VW"} for value-weighted or \code{"EW"} for equal-weighted.
}
}
\examples{
\dontrun{
  download_data_huggingface(
    "high_frequency_sp500", "2007-07-26", "2007-07-27"
  )
  download_data_huggingface(
    "factor_library",
    sorting_variable = "52w",
    rebalancing = "annual"
  )
  download_data_huggingface(
    "factor_library", sorting_variable = "ag", fill_all = TRUE
  )
}
}
\seealso{
Other download functions: 
\code{\link{download_data}()},
\code{\link{download_data_constituents}()},
\code{\link{download_data_factors_ff}()},
\code{\link{download_data_factors_q}()},
\code{\link{download_data_fred}()},
\code{\link{download_data_macro_predictors}()},
\code{\link{download_data_osap}()},
\code{\link{download_data_risk_free}()},
\code{\link{download_data_stock_prices}()}
}
\concept{download functions}
