% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/fit.R
\name{imr}
\alias{imr}
\title{Fit the Integrative Bayesian Multi-Platform Regression Model}
\usage{
imr(
  platform_data_list,
  outcome,
  cov = NULL,
  type_outcome = c("right.censored", "binary", "continuous"),
  method = c("IMR", "BMS"),
  ssize = 30,
  nu = rep(-3, length(platform_data_list)),
  hh = 0.087,
  h0 = 10000,
  sig_alpha_psi = c(0.001, 0.001),
  thet_alph_bet = c(40, 10),
  sample_mcmc = c(2000, 1000),
  seed = NULL,
  verbose = FALSE
)
}
\arguments{
\item{platform_data_list}{A list of data frames, one per platform.  Each
data frame must contain an `id` column (the subject identifier, taken to be
the first column); the remaining columns are finite numeric features
measured on that platform.  Subject identifiers must be unique within each
data frame.  The `id` column links subjects across platforms and to the
outcome and covariate data.}

\item{outcome}{A data frame containing an `id` column and the response.  For
`type_outcome = "right.censored"` it must also contain the event/censoring
time and a censoring indicator (three columns in total).  For `"binary"`
the response must be coded 0/1 and for `"continuous"` it is a numeric
response (two columns in total).  The `id` column must be first and unique.}

\item{cov}{An optional data frame of clinical covariates including an `id`
column followed by finite numeric covariates.  Covariates are always
included in every regression (they are not subject to selection).  Defaults
to `NULL` (no covariates).}

\item{type_outcome}{Character string specifying the outcome type, one of
`"right.censored"` (default), `"binary"` or `"continuous"`.}

\item{method}{Character string specifying the method, `"IMR"` (default) for
the integrative model that shares information across subgroups via the MRF
prior, or `"BMS"` for the non-integrative Bayesian multi-step variant that
fits each subgroup independently (MRF interaction parameters set to zero).}

\item{ssize}{Minimum availability subgroup size for a subgroup to be
modelled. Subgroups with at most `ssize` subjects are dropped. Default is
`30`.}

\item{nu}{A numeric vector of prior log-odds of inclusion, one value per
platform, controlling the prior sparsity of the selected features.
Defaults to `rep(-3, length(platform_data_list))`.}

\item{hh}{Scale of the non-local (product moment) prior on the slab
regression effects (default `0.087`).}

\item{h0}{Prior variance of the intercept (default `10000`).}

\item{sig_alpha_psi}{Length-2 numeric vector with the shape and rate of the
inverse-gamma prior on the response error variance (default
`c(0.001, 0.001)`).  Ignored when `type_outcome = "binary"`: a probit model
has residual variance fixed at 1 for identifiability, so the error variance
is pinned to 1 rather than estimated.}

\item{thet_alph_bet}{Length-2 numeric vector with the shape and rate of the
gamma prior on the MRF interaction parameters theta, which borrow
information across subgroups (default `c(40, 10)`).}

\item{sample_mcmc}{An integer vector `c(n_retained, n_burnin)` giving the
number of post-burn-in draws to retain and the number of burn-in
iterations to discard.  The sampler runs `n_retained + n_burnin`
iterations in total, so the returned `log_posterior` has
`sum(sample_mcmc)` entries.  Default is `c(2000, 1000)`.}

\item{seed}{Optional integer seed for the sampler.  If `NULL` (the default) a
seed is drawn from the current R RNG state, so a run is reproducible
whenever [set.seed()] is called beforehand or an explicit `seed` is passed.}

\item{verbose}{Logical; if `TRUE`, print the sampler's progress and
diagnostics to the console.  Defaults to `FALSE` (quiet).}
}
\value{
An object of class `"imr"`: a list with components
\item{gam_mean}{List (one matrix per platform) of posterior mean
  variable-selection probabilities; rows index the subgroups containing the
  platform and columns index the platform features.}
\item{theta_mean}{List (one matrix per platform) of posterior mean MRF
  interaction parameters between subgroups.}
\item{estimate_latent_y}{List (one vector per subgroup) of posterior mean
  latent responses, useful for censored or binary data.}
\item{log_posterior}{Numeric vector of log-posterior values across all MCMC
  iterations (burn-in included).}
\item{gam_sample}{Post-burn-in MCMC samples of the selection indicators.}
\item{theta_sample}{Post-burn-in MCMC samples of the MRF interaction
  parameters (absent when `method = "BMS"`).}
\item{list_hyperpara, data1, data2}{Hyper-parameters and pre-processed data
  retained for prediction and cross-validation.}
\item{call, type_outcome, n_platform, platform_names, feature_names,
  covariate_names, model_bitstrings, sample_size, model_platforms,
  platform_models, sample_mcmc, nu, method}{Run metadata used by the print,
  summary, plot and predict methods.}
}
\description{
`imr()` fits the integrative multi-regression (IMR) model of Chekouo et al.
(2017) by Markov chain Monte Carlo (MCMC).
It identifies biomarkers associated with a time-to-event, binary or
continuous outcome while borrowing information across all subjects,
regardless of which platforms each subject has measured.  Subjects are
partitioned into availability subgroups defined by their pattern of platform
availability; one regression is built per subgroup and information is shared
across subgroups through a Markov random field (MRF) prior on the
variable-selection indicators together with non-local priors on the
regression coefficients.  The sampler is implemented in C for efficiency.

The arguments are grouped by the orthogonal aspect of the analysis that each
one controls: the *data* (`platform_data_list`, `outcome`, `cov`), the
*likelihood* (`type_outcome`), the *model* (`method`), subgroup *filtering*
(`ssize`), the *priors* (`nu`, `hh`, `h0`, `sig_alpha_psi`, `thet_alph_bet`),
the *computation* (`sample_mcmc`, `seed`) and the *output* (`verbose`).
}
\details{
All feature and covariate data are standardized internally (mean 0, standard
deviation 1); the centring and scaling factors are stored in the returned
object so that [predict.imr()] can apply the same transformation to new
subjects.  For right-censored outcomes the latent log-survival times of
censored subjects are imputed within the sampler; for binary outcomes a
probit data-augmentation latent variable is sampled.
}
\examples{
\donttest{
data("simIMR", package = "IntegMultiReg")
fit <- imr(
  platform_data_list = simIMR$platforms,
  outcome = simIMR$outcome,
  cov = simIMR$covariates,
  type_outcome = "binary",
  nu = c(-4, -3, -4),
  sample_mcmc = c(200, 100),
  ssize = 5,
  seed = 1
)
fit
}
}
\references{
Chekouo T, Stingo FC, Doecke JD, Do K-A (2017). "A Bayesian Integrative
Approach for Multi-Platform Genomic Data: A Kidney Cancer Case Study."
\emph{Biometrics}, \strong{73}(2), 615--624. \doi{10.1111/biom.12587}
}
\seealso{
[predict.imr()], [cv_imr()], [summary.imr()], [plot.imr()]
}
