% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/maxent_run.R
\name{maxent_run}
\alias{maxent_run}
\title{Run a Complete Maxent Species Distribution Modelling Workflow}
\usage{
maxent_run(
  species,
  env_grids,
  occ_df,
  output_dir,
  lon_col = "long",
  lat_col = "lat",
  n_background = 10000L,
  types = c("linear", "quadratic", "hinge"),
  n_hinges = 15L,
  max_iter = 500L,
  seed = 42L,
  bias_weights = NULL,
  response_curves = TRUE,
  pictures = TRUE
)
}
\arguments{
\item{species}{Character: species name (used in file names and the
console report).}

\item{env_grids}{Named list of external pointers to Grid<float> objects.
The \emph{names} of the list are used as the environmental variable names.}

\item{occ_df}{A \code{data.frame} (or CSV path) with occurrence
records.}

\item{output_dir}{Character: directory where all output files are written
(created if it does not exist).}

\item{lon_col}{Character: longitude column name in \code{occ_df}
(default \code{"long"}).}

\item{lat_col}{Character: latitude column name in \code{occ_df}
(default \code{"lat"}).}

\item{n_background}{Integer: number of background points (default 10000).}

\item{types}{Character vector of feature types passed to
\code{\link{maxent_generate_features}} (default
\code{c("linear", "quadratic", "hinge")}).}

\item{n_hinges}{Integer: number of hinge knots (default 15).}

\item{max_iter}{Integer: maximum training iterations (default 500).}

\item{seed}{Integer: random seed for background sampling
(default 42).}

\item{bias_weights}{Optional numeric vector of per-background-point bias
weights.  Must have length equal to \code{n_background} (the background
points only, not including occurrence points).  When supplied, the
background density is weighted by \code{bias[i] * exp(lp[i] - lpn)},
mirroring Java Maxent's \code{biasFile}.  Pass \code{NULL} (default)
for uniform (unbiased) background.}

\item{response_curves}{Logical: write response curve PNGs
(default \code{TRUE}).}

\item{pictures}{Logical: write prediction map PNG (default \code{TRUE}).}
}
\value{
A named list with:
  \describe{
    \item{model}{Trained FeaturedSpace external pointer.}
    \item{fit_result}{List returned by \code{\link{maxent_fit}}.}
    \item{evaluation}{List returned by \code{\link{maxent_evaluate}}.}
    \item{contributions}{Data.frame of percent contributions.}
    \item{permutation_importance}{Data.frame of permutation importances.}
    \item{output_dir}{The output directory used.}
  }
}
\description{
Provides a single high-level entry point that mirrors running the Java
Maxent GUI with one click.  Starting from raw environmental grids and
occurrence records, the function:
\enumerate{
  \item Reads and validates occurrence records.
  \item Samples background points.
  \item Extracts environmental values and builds features.
  \item Trains the Maxent model.
  \item Projects the model onto the full landscape (cloglog output).
  \item Evaluates model performance (AUC).
  \item Computes percent contribution and permutation importance.
  \item Writes all standard output files (lambdas, prediction PNG, response
    curve PNGs, omission CSV, sample-predictions CSV, and
    \code{maxentResults.csv}).
  \item Prints a performance summary to the console.
}
}
\examples{
\donttest{
stack_path      <- system.file("extdata", "stack_1_12_crop.rds",
                               package = "maxentcpp")
example_rasters <- terra::unwrap(readRDS(stack_path))
grids <- list(
  bio1  = maxent_grid_from_terra(example_rasters[[1]]),
  bio12 = maxent_grid_from_terra(example_rasters[[2]])
)
data(example_occ_df)

result <- maxent_run(
  species    = "Abeillia_abeillei",
  env_grids  = grids,
  occ_df     = example_occ_df,
  output_dir = tempdir(),
  lon_col    = "long",
  lat_col    = "lat")

result$evaluation$auc
}
}
