% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/coxstream_arrow.R
\name{coxstream_arrow}
\alias{coxstream_arrow}
\title{Fit a Cox PH model by streaming a DESC-sorted parquet file}
\usage{
coxstream_arrow(
  parquet_path,
  x_cols,
  time_col = "duration",
  event_col = "event",
  init = NULL,
  max_iter = 25L,
  tol = 1e-08,
  batch_size = 250000L,
  verbose = TRUE
)
}
\arguments{
\item{parquet_path}{Path to a parquet file sorted by time DESCENDING.}

\item{x_cols}{Character vector of covariate column names.}

\item{time_col}{Column name for event/censoring time. Default \code{"duration"}.}

\item{event_col}{Column name for event indicator (1 = event). Default \code{"event"}.}

\item{init}{Optional starting values for beta (length p). Default zero.}

\item{max_iter}{Maximum NR iterations. Default 25.}

\item{tol}{Convergence tolerance on ||NR step|| (L2 norm of beta
update). Default 1e-8. Same criterion as the Python
coxstream implementations.}

\item{batch_size}{Target rows per read call. Consecutive row groups are
merged until the total reaches this size, then freed (with a
gc()) before the next is read, so peak RAM is O(batch_size *
p), flat in n. The default 250 000 keeps RAM genuinely flat;
larger chunks are slightly faster but let the allocator's
high-water ratchet up, so RAM regains a mild upward drift.}

\item{verbose}{Print per-iteration progress. Default TRUE.}
}
\value{
A \code{"coxstream"} object (same class as \code{coxstream()}).
}
\description{
Like \code{coxstream()} but reads data row-group by row-group from parquet.
Peak RAM is O(batch_size * p) for the active chunk plus O(p^2) for the
carry state, independent of total n. Uses exact Efron tie correction: tie
groups that span row-group boundaries are handled via local carry state,
giving bit-identical coefficients to \code{coxstream()} on any data.
}
\details{
Each NR iteration reads one row-group chunk at a time with \code{mmap = FALSE}
(pread into heap buffers freed after each chunk -- a memory-mapped reader
would instead leave every touched file page resident for the mapping's
lifetime, making RSS grow O(n)). Each chunk is exported to a C
\code{ArrowArrayStream} and consumed zero-copy in C++ by
\code{efron_stream_chunk_inplace()}, with the Efron tie-state carried across
chunks in R -- no R-level column materialisation (\code{as.vector} / \code{cbind} /
\code{concat_tables}), which is what previously left a ~1.5x gap behind the Python
streaming path.
}
