Package {maxentcpp}

Convert Grid to Raster Matrix

Description

Extracts grid data as an R matrix.

Usage

as_matrix(grid)

Arguments

Value

Numeric matrix

Clamp Environmental Grids

Description

Restricts environmental variable values to the training range. Returns clamped grids and a clamping indicator grid.

Usage

clamp_grids(grid_ptrs, var_mins, var_maxs)

Arguments

Value

A named list with:

clamped_grids

List of external pointers to clamped Grid<float>

clamp_grid

External pointer to Grid<float> with clamping magnitudes

Compute MESS (Multivariate Environmental Similarity Surface)

Description

Measures how similar each cell is to the training environment. Negative values indicate novel (non-analog) conditions.

Usage

compute_mess(grid_ptrs, reference_values, feature_names)

Arguments

Value

A named list with:

mess_grid

External pointer to Grid<float> with MESS values

mod_grid

External pointer to Grid<float> with MoD variable index (1-based)

Compute MESS from Min/Max Ranges

Description

Simplified MESS using only the min/max of reference data.

Usage

compute_mess_range(grid_ptrs, var_mins, var_maxs)

Arguments

Value

A named list with mess_grid and mod_grid (external pointers).

Compute Percent Contribution

Description

Computes variable contribution based on sum of absolute lambda values for features derived from each variable.

Usage

compute_percent_contribution(fs_ptr, feature_names)

Arguments

Value

A data.frame with columns: name, contribution.

Compute Permutation Importance

Description

Measures how much each environmental variable contributes to model prediction quality by permuting each variable and measuring AUC drop.

Usage

compute_permutation_importance(
  fs_ptr,
  grid_ptrs,
  feature_names,
  presence_rows,
  presence_cols,
  absence_rows,
  absence_cols,
  seed = 42L
)

Arguments

Value

A data.frame with columns: name, permutation_importance.

Compute Java-compatible Marginal Response Curve

Description

Like compute_response_curve() but applies the Java Maxent cloglog: cloglog_java = 1 - exp(-exp(H) * raw_java)

Usage

compute_response_curve(
  fs_ptr,
  grid_ptrs,
  feature_names,
  var_index,
  n_steps = 100L
)

Arguments

Details

This matches the response curves produced by Java Maxent and dismo.

Value

A data.frame with columns: value, prediction.

Compute Java-compatible Response Curve with Fixed Values

Description

Like compute_response_curve_fixed() but applies the Java Maxent cloglog: cloglog_java = 1 - exp(-exp(H) * raw_java)

Usage

compute_response_curve_fixed(
  fs_ptr,
  fixed_values,
  feature_names,
  var_index,
  var_min,
  var_max,
  n_steps = 100L
)

Arguments

Value

A data.frame with columns: value, prediction.

Compute Variable Ranges from Grids

Description

Scans all valid cells to determine min/max of each variable.

Usage

compute_variable_ranges(grid_ptrs)

Arguments

Value

A data.frame with columns: min, max.

Convert geographic coordinates to row/col

Description

Convert geographic coordinates to row/col

Usage

coords_to_rowcol(dim_ptr, lon, lat)

Arguments

Value

Integer vector with row and column indices

Create a GridDimension object

Description

Creates a grid dimension specifying the spatial extent and resolution

Usage

create_grid_dimension(nrows, ncols, xll, yll, cellsize)

Arguments

Value

External pointer to GridDimension object

Create a float Grid object

Description

Creates a raster grid for environmental variables

Usage

create_grid_float(dim_ptr, name, nodata_value = -9999)

Arguments

Value

External pointer to Grid<float> object

Create a HingeFeature object

Description

Creates a piecewise-linear hinge feature. Forward hinge: eval(i) = (values[i] > min_knot) ? (values[i] - min_knot) / (max_knot - min_knot) : 0. Reverse hinge: eval(i) = (values[i] < max_knot) ? (max_knot - values[i]) / (max_knot - min_knot) : 0.

Usage

create_hinge_feature(values, name, min_knot, max_knot, is_reverse = FALSE)

Arguments

Value

External pointer to HingeFeature object

Create a Layer metadata object

Description

Create a Layer metadata object

Usage

create_layer(name, type_str)

Arguments

Value

External pointer to a Layer object.

Create a LinearFeature object

Description

Creates a linear (normalized) feature: eval(i) = (values[i] - min) / (max - min). Returns 0 when min == max.

Usage

create_linear_feature(values, name, min_val, max_val)

Arguments

Value

External pointer to LinearFeature object

Create a ProductFeature object

Description

Creates a product (interaction) feature between two environmental variables: eval(i) = norm(values1[i]) * norm(values2[i]).

Usage

create_product_feature(values1, values2, name, min1, max1, min2, max2)

Arguments

Value

External pointer to ProductFeature object

Create a QuadraticFeature object

Description

Creates a quadratic feature: eval(i) = linear_val^2 where linear_val = (values[i] - min) / (max - min).

Usage

create_quadratic_feature(values, name, min_val, max_val)

Arguments

Value

External pointer to QuadraticFeature object

Create a Sample object

Description

Creates a species occurrence sample point

Usage

create_sample(point, row, col, lat, lon, name)

Arguments

Value

External pointer to Sample object

Create a ThresholdFeature object

Description

Creates a binary step feature: eval(i) = 1.0 if values[i] > threshold, else 0.0.

Usage

create_threshold_feature(values, name, threshold)

Arguments

Value

External pointer to ThresholdFeature object

Close a CsvReader

Description

Close a CsvReader

Usage

csv_close(reader_ptr)

Arguments

Value

Called for side effects; returns invisibly.

Get CSV column headers

Description

Get CSV column headers

Usage

csv_headers(reader_ptr)

Arguments

Value

Character vector of header names.

Read the next CSV record

Description

Read the next CSV record

Usage

csv_next_record(reader_ptr)

Arguments

Value

Character vector of field values, or NULL on EOF.

Open a CSV file for reading

Description

Open a CSV file for reading

Usage

csv_open(filename, has_header = TRUE)

Arguments

Value

External pointer to a CsvReader object.

Read an entire named column as doubles

Description

Reads from the current position to EOF.

Usage

csv_read_double_column(reader_ptr, field)

Arguments

Value

Numeric vector.

Close a CsvWriter

Description

Close a CsvWriter

Usage

csv_writer_close(writer_ptr)

Arguments

Value

Called for side effects; returns invisibly.

Open a CSV file for writing

Description

Open a CSV file for writing

Usage

csv_writer_open(filename, append = FALSE, precision = 4L)

Arguments

Value

External pointer to a CsvWriter object.

Write a value into the current row of a CSV

Description

Write a value into the current row of a CSV

Usage

csv_writer_print(writer_ptr, column, value)

Arguments

Value

Called for side effects; returns invisibly.

Write a numeric value into the current row of a CSV

Description

Write a numeric value into the current row of a CSV

Usage

csv_writer_print_double(writer_ptr, column, value)

Arguments

Value

Called for side effects; returns invisibly.

Flush the current CSV row to disk

Description

Flush the current CSV row to disk

Usage

csv_writer_println(writer_ptr)

Arguments

Value

Called for side effects; returns invisibly.

Compute AUC (Area Under the ROC Curve)

Description

Computes the Wilcoxon-Mann-Whitney AUC statistic from prediction scores at presence and absence sites.

Usage

eval_auc(presence, absence)

Arguments

Value

A named list with elements: auc, max_kappa, max_kappa_thresh.

Compute Pearson Correlation

Description

Computes Pearson correlation coefficient between two numeric vectors.

Usage

eval_correlation(x, y)

Arguments

Value

Correlation coefficient in [-1, 1].

Compute Log-Loss

Description

Computes average cross-entropy log-loss from predictions at presence and absence sites.

Usage

eval_logloss(presence, absence)

Arguments

Value

Average log-loss value.

Compute Misclassification Rate

Description

Fraction of misclassified samples at threshold 0.5.

Usage

eval_misclassification(presence, absence)

Arguments

Value

Misclassification rate in [0, 1].

Full Model Evaluation

Description

Computes all evaluation metrics at once: AUC, correlation, log-loss, squared error, misclassification, max kappa, and prevalence.

Usage

eval_model(presence, absence)

Arguments

Value

A named list with: auc, max_kappa, max_kappa_thresh, correlation, square_error, logloss, misclassification, prevalence.

Compute Mean Squared Error

Description

Presence sites contribute (1-pred)^2, absence sites contribute pred^2.

Usage

eval_square_error(presence, absence)

Arguments

Value

Mean squared error.

Species occurrence points from Abeillia abeillei presence points after download and clean from GBIF. This is a hummingbird example. A dataset with three variables. Contains scientific name, longitude and latitude.

Description

Species occurrence points from Abeillia abeillei presence points after download and clean from GBIF. This is a hummingbird example. A dataset with three variables. Contains scientific name, longitude and latitude.

Usage

example_occ_df

Format

A data frame with 73 rows and 3 variables:

species

Species name

long

Decimal longitude geographical coordinate, in degrees

lat

Decimal latitude geographical coordinate, in degrees

Source

<doi:10.1016/j.ecolmodel.2021.109823>

Extract Java-compatible Raw Predictions at Sample Locations

Description

Gets Java Maxent raw scores (raw_java = exp(lp - lpNorm) / densityNorm) at specific grid cell locations.

Usage

extract_predictions_raw(fs_ptr, grid_ptrs, feature_names, rows, cols)

Arguments

Value

Numeric vector of Java raw scores. NaN for NODATA cells.

Evaluate a feature at a given index

Description

Evaluate a feature at a given index

Usage

feature_eval(feature_ptr, index)

Arguments

Value

Feature value at that index (double)

Get feature metadata

Description

Returns a list with name, type, lambda, min, and max values.

Usage

feature_get_info(feature_ptr)

Arguments

Value

Named list with feature properties

Generate features from a list of environmental variable vectors

Description

Generates all configured feature types (linear, quadratic, product, threshold, hinge) from the supplied data vectors.

Usage

generate_features(
  data_list,
  feature_types = as.character(c("linear", "quadratic", "product", "threshold", "hinge")),
  n_thresholds = 10L,
  n_hinges = 10L
)

Arguments

Value

List of external pointers to Feature objects

Get grid dimension properties

Description

Get grid dimension properties

Usage

get_grid_dimension_info(dim_ptr)

Arguments

Value

List with dimension properties

Get layer metadata

Description

Get layer metadata

Usage

get_layer_info(layer_ptr)

Arguments

Value

Named list with name and type (string).

Get sample properties

Description

Get sample properties

Usage

get_sample_info(sample_ptr)

Arguments

Value

List with sample properties

Create a GridFloat from an R matrix

Description

Create a GridFloat from an R matrix

Usage

grid_float_from_matrix(mat, xll, yll, cellsize, nodata = -9999, name = "")

Arguments

Value

External pointer to a GridFloat object.

Get grid information for an ASC-loaded grid

Description

Returns metadata and basic statistics for a GridFloat.

Usage

grid_float_info(grid_ptr)

Arguments

Value

Named list with nrows, ncols, xll, yll, cellsize, nodata, name, count_data.

Extract the data from a GridFloat as an R matrix

Description

Extract the data from a GridFloat as an R matrix

Usage

grid_float_to_matrix(grid_ptr)

Arguments

Value

Numeric matrix (nrows × ncols). NODATA cells are set to NA.

Set grid from matrix

Description

Set grid from matrix

Usage

grid_from_matrix(grid_ptr, mat)

Arguments

Value

Called for side effects; returns invisibly.

Get grid value

Description

Get grid value

Usage

grid_get_value(grid_ptr, row, col)

Arguments

Value

Grid value

Extract multiple values from a Grid at given row/col indices (batch)

Description

Extract multiple values from a Grid at given row/col indices (batch)

Usage

grid_get_values_batch(grid_ptr, rows, cols)

Arguments

Value

Numeric vector of extracted values (NA for NODATA cells).

Check if grid cell has data

Description

Check if grid cell has data

Usage

grid_has_data(grid_ptr, row, col)

Arguments

Value

TRUE if cell has valid data

Get Grid Information

Description

Retrieves properties of a grid object.

Usage

grid_info(grid)

Arguments

Value

List with grid properties

Read an ESRI ASCII grid (.asc) file

Description

Reads an ASC raster file and returns a float Grid external pointer.

Usage

grid_read_asc(filename)

Arguments

Value

External pointer to a GridFloat object.

Read a grid from file (auto-detect format)

Description

Currently supports .asc format. Returns a float Grid.

Usage

grid_read_file(filename)

Arguments

Value

External pointer to a GridFloat object.

Set grid value

Description

Set grid value

Usage

grid_set_value(grid_ptr, row, col, value)

Arguments

Value

Called for side effects; returns invisibly.

Get grid as matrix

Description

Get grid as matrix

Usage

grid_to_matrix(grid_ptr)

Arguments

Value

Numeric matrix of grid values

Write a float Grid to an ESRI ASCII (.asc) file

Description

Write a float Grid to an ESRI ASCII (.asc) file

Usage

grid_write_asc(grid_ptr, filename, scientific = TRUE)

Arguments

Value

Called for side effects; returns invisibly.

Extract a layer name from a file path

Description

Strips directory and extension, e.g. "/data/bio1.asc" → "bio1".

Usage

layer_name_from_path(path)

Arguments

Value

Character: layer name.

Append a Row to maxentResults.csv

Description

Appends one row of species-level summary statistics to a maxentResults.csv file, creating the file (with a header) if it does not yet exist. Column names match the Java Maxent output for cross-tool compatibility.

Usage

maxent_append_results_csv(
  results_file,
  species,
  n_training,
  n_test = 0L,
  training_gain,
  training_auc,
  test_gain = NA_real_,
  test_auc = NA_real_,
  entropy,
  contributions_df,
  perm_imp_df
)

Arguments

Value

Invisibly returns results_file.

Examples

maxent_append_results_csv(
  file.path(tempdir(), "maxentResults.csv"),
  species = "Sp1", n_training = 50L, training_gain = 1.23,
  training_auc = 0.95, entropy = 6.7,
  contributions_df = contrib, perm_imp_df = perm_imp)

Compute AUC (Area Under the ROC Curve)

Description

Computes the Wilcoxon-Mann-Whitney AUC statistic from prediction scores at presence and absence sites. Also returns max-Kappa and its threshold.

Usage

maxent_auc(presence, absence)

Arguments

Value

A named list with elements:

auc

AUC value in [0, 1]

max_kappa

Best Cohen's Kappa found

max_kappa_thresh

Threshold at best Kappa

Examples

result <- maxent_auc(c(0.8, 0.9, 1.0), c(0.1, 0.2, 0.3))
result$auc  # 1.0

Generate Background Sample Indices

Description

Randomly selects valid (non-NODATA) cells from a reference grid for use as background points in MaxEnt modeling.

Usage

maxent_background_indices(grid, n = 10000L, seed = NULL)

Arguments

Value

A named list with:

rows

Integer vector of row indices (0-based).

cols

Integer vector of column indices (0-based).

indices

Integer vector of 0-based flat indices (row * ncols + col), suitable for maxent_featured_space.

Examples

dim <- maxent_dimension(100, 100, -120, 35, 0.1)
grid <- maxent_grid(dim, "env1")
bg <- maxent_background_indices(grid, n = 5000, seed = 42)
bg$indices  # 0-based flat indices for FeaturedSpace

Clamp Environmental Grids

Description

Restricts environmental variable values to the range observed during training. Values below min are set to min, values above max are set to max. A clamping grid records the total absolute clamping at each cell.

Usage

maxent_clamp(env_grids, var_mins, var_maxs)

Arguments

Value

A named list with:

clamped_grids

List of external pointers to clamped grids

clamp_grid

External pointer to clamping magnitude grid

Examples

result <- maxent_clamp(list(g1, g2), c(0, 50), c(30, 200))
clamped <- result$clamped_grids
clamp_mat <- maxent_grid_to_matrix(result$clamp_grid)

Generate the Maxent Canonical Color Ramp

Description

Produces a vector of hex color strings matching the color ramp used by the Java Maxent software (density/Display.java::showColor()). The default palette cycles Red → Yellow → Green → Cyan → Blue across 1020 steps, with higher values rendered as red and lower values as blue.

Usage

maxent_color_ramp(n = 1020L, mode = "plain")

Arguments

Value

Character vector of n hex color strings of the form "#RRGGBB".

Examples

pal <- maxent_color_ramp(1020)
pal[1]     # "#FF0000"  (max value → red)
pal[510]   # near "#00FF00" (mid-point → green)
pal[1020]  # "#0000FF"  (min value → blue)

Compute Pearson Correlation

Description

Computes the Pearson correlation coefficient between two numeric vectors.

Usage

maxent_correlation(x, y)

Arguments

Value

Correlation coefficient in [-1, 1].

Examples

maxent_correlation(c(1, 2, 3), c(2, 4, 6))  # 1.0

Close a CSV Reader

Description

Close a CSV Reader

Usage

maxent_csv_close(reader)

Arguments

Value

Invisibly returns NULL.

Get CSV Column Headers

Description

Get CSV Column Headers

Usage

maxent_csv_headers(reader)

Arguments

Value

Character vector of column names.

Read the Next CSV Record

Description

Read the Next CSV Record

Usage

maxent_csv_next(reader)

Arguments

Value

Character vector of field values, or NULL on EOF.

Open a CSV File for Reading

Description

Opens a CSV file and reads column headers.

Usage

maxent_csv_open(filename, has_header = TRUE)

Arguments

Value

External pointer to a CsvReader C++ object.

Read an Entire Column as Doubles

Description

Reads from the current file position to EOF.

Usage

maxent_csv_read_column(reader, field)

Arguments

Value

Numeric vector.

Write a String Value to the Current CSV Row

Description

Adds a column = value pair (as a character string) to the current row buffer. Call maxent_csv_write_row to flush the row.

Usage

maxent_csv_write(writer, column, value)

Arguments

Value

Invisibly returns the writer object.

Close a CSV Writer

Description

Flushes any pending data and closes the CSV file.

Usage

maxent_csv_write_close(writer)

Arguments

Value

Invisibly returns NULL.

Write a Numeric Value to the Current CSV Row

Description

Adds a column = value pair (as a double) to the current row buffer. Call maxent_csv_write_row to flush the row.

Usage

maxent_csv_write_num(writer, column, value)

Arguments

Value

Invisibly returns the writer object.

Open a CSV File for Writing

Description

Opens a CSV file and returns a writer object. Use maxent_csv_write, maxent_csv_write_num, maxent_csv_write_row, and maxent_csv_write_close to write data and close the file.

Usage

maxent_csv_write_open(filename, append = FALSE, precision = 4L)

Arguments

Value

External pointer to a CsvWriter C++ object.

Flush the Current Row to the CSV File

Description

Writes all buffered column values as a single CSV row and starts a new row buffer.

Usage

maxent_csv_write_row(writer)

Arguments

Value

Invisibly returns the writer object.

Create a Grid Dimension Object

Description

Defines the spatial extent and resolution of a raster grid.

Usage

maxent_dimension(nrows, ncols, xll, yll, cellsize)

Arguments

Value

GridDimension object (external pointer)

Examples

dim <- maxent_dimension(
  nrows = 100, ncols = 100,
  xll = -120.0, yll = 35.0,
  cellsize = 0.1
)

Full Model Evaluation

Description

Computes all evaluation metrics at once: AUC, correlation, log-loss, squared error, misclassification, max Kappa, and prevalence.

Usage

maxent_evaluate(presence, absence)

Arguments

Value

A named list with:

auc

AUC value

max_kappa

Best Cohen's Kappa

max_kappa_thresh

Threshold at best Kappa

correlation

Pearson correlation with labels

square_error

Mean squared error

logloss

Cross-entropy log-loss

misclassification

Misclassification rate

prevalence

Fraction of presence sites

Examples

res <- maxent_evaluate(c(0.9, 0.85, 0.95), c(0.1, 0.15, 0.2))
res$auc          # 1.0
res$correlation  # > 0

Extract Lambda Values from a Maxent Run Result

Description

Retrieves the trained lambda (weight) coefficients from the output of maxent_run, returning them as a named numeric vector. Each element is the lambda value for the corresponding feature, and the name of each element is the feature name (e.g. "bio1", "bio1^2", "bio1'1").

Usage

maxent_extract_lambdas(run_result)

Arguments

Details

The function reads lambdas directly from the trained model object, so it also works correctly after reloading coefficients with maxent_load_lambdas.

Value

A named numeric vector of lambda values, one per feature. Names are the feature names as stored in the model.

Examples

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")

lambdas <- maxent_extract_lambdas(result)
print(lambdas)

Extract environmental values for occurrences from a terra SpatRaster

Description

Streams finite raster rows through the same callback-backed provider path used by maxent_featured_space_from_rast, then returns values at occurrence locations.

Usage

maxent_extract_occurrence_env_terra(
  rast,
  occurrences,
  lon_col = "longitude",
  lat_col = "latitude"
)

Arguments

Value

Numeric matrix with one row per retained occurrence and one column per raster layer.

Extract occurrence environmental values from a callback stream

Description

Drains a callback background stream once and returns the rows at the requested 0-based finite-stream indices.

Usage

maxent_extract_occurrence_from_callback(
  num_points,
  num_layers,
  occurrence_indices,
  next_tile_fn,
  reset_fn,
  preserved_rast = NULL
)

Arguments

Value

Numeric matrix with one row per requested occurrence index.

Extract Cloglog Predictions at Sample Locations

Description

Gets Java Maxent cloglog scores at specific grid cell locations:

cloglog = 1 - exp(-exp(H) \cdot raw)

Usage

maxent_extract_predictions_cloglog(model, env_grids, feature_names, rows, cols)

Arguments

Value

Numeric vector of cloglog scores in [0, 1]. NaN for NODATA cells.

See Also

maxent_extract_predictions_raw, maxent_project_cloglog

Extract Logistic Predictions at Sample Locations

Description

Gets Java Maxent logistic scores at specific grid cell locations:

logistic = \frac{exp(H) \cdot raw}{1 + exp(H) \cdot raw}

Usage

maxent_extract_predictions_logistic(
  model,
  env_grids,
  feature_names,
  rows,
  cols
)

Arguments

Value

Numeric vector of logistic scores in [0, 1]. NaN for NODATA cells.

See Also

maxent_extract_predictions_raw, maxent_project_logistic

Extract Raw Predictions at Sample Locations

Description

Gets Java Maxent raw scores at specific grid cell locations:

raw = \frac{exp(lp - lpNorm)}{densityNorm}

Usage

maxent_extract_predictions_raw(model, env_grids, feature_names, rows, cols)

Arguments

Details

This matches the raw output of Java Maxent and dismo.

Value

Numeric vector of Java raw scores. NaN for NODATA cells.

See Also

maxent_project_raw

Evaluate a Feature at a Given Index

Description

Evaluates the feature function at the specified index (1-based, as is standard in R). Internally converts to 0-based indexing for C++.

Usage

maxent_feature_eval(feature, index)

Arguments

Value

Numeric scalar: the feature value at that index.

Examples

vals <- c(0, 5, 10)
f <- maxent_linear_feature(vals, "temp")
maxent_feature_eval(f, 2)  # 5/10 = 0.5

Get Feature Properties

Description

Returns a list of metadata for a feature object.

Usage

maxent_feature_info(feature)

Arguments

Value

Named list with elements: name, type, lambda, min, max, size.

Examples

vals <- c(0, 5, 10)
f <- maxent_linear_feature(vals, "temp")
maxent_feature_info(f)

Create a FeaturedSpace Object

Description

Constructs a MaxEnt FeaturedSpace from background point data, occurrence sample indices, and a list of pre-built Feature objects.

Usage

maxent_featured_space(
  num_points,
  sample_indices,
  features,
  bias_weights = NULL
)

Arguments

Value

External pointer to a FeaturedSpace C++ object.

Examples

n   <- 100L
idx <- 90:99  # 0-based sample indices
env <- seq(0, 1, length.out = n)
f   <- maxent_linear_feature(env, "env1")
fs  <- maxent_featured_space(n, idx, list(f))

Create a FeaturedSpace object

Description

Constructs a MaxEnt FeaturedSpace from background point count, occurrence sample indices, and a list of Feature objects.

Usage

maxent_featured_space_create(
  num_points,
  sample_indices,
  feature_ptrs,
  bias_weights = numeric(0)
)

Arguments

Value

External pointer to a FeaturedSpace object.

Create a FeaturedSpace from a streaming background provider

Description

Builds a FeaturedSpace by draining a callback-style background provider (typically backed by a terra::SpatRaster block loop) one tile at a time, then constructing features from the concatenated (num_points x num_layers) matrix via generate_features.

Usage

maxent_featured_space_from_callback(
  num_points,
  num_layers,
  layer_names,
  sample_indices,
  feature_types,
  n_thresholds,
  n_hinges,
  next_tile_fn,
  reset_fn,
  use_cache = TRUE
)

Arguments

Details

This is the C++ entry point used by maxent_featured_space_from_rast; end users should prefer that R-level wrapper.

Value

External pointer to a FeaturedSpace object.

Create a FeaturedSpace directly from a terra SpatRaster

Description

Streams a terra::SpatRaster block-by-block into the C++ FeaturedSpace streaming constructor, filtering NA cells on the fly and handing the concatenated (num_points x nlyr(rast)) matrix to maxent_generate_features so feature objects are built inside C++ without the R caller having to materialise the full raster stack first.

Usage

maxent_featured_space_from_rast(
  rast,
  sample_indices,
  feature_types = c("linear", "quadratic", "product", "threshold", "hinge"),
  n_thresholds = 10L,
  n_hinges = 10L,
  enable_streaming_eval = TRUE
)

Arguments

Details

This is the Phase E.2 entry point described in docs/ARCHITECTURE_terra_raster.md (sections 3.1 and 3.2). The result is bit-for-bit identical to the dense path (maxent_generate_features -> maxent_featured_space) when the same data, sample indices, and feature configuration are used.

Value

External pointer to a FeaturedSpace object.

See Also

maxent_featured_space, maxent_featured_space_from_callback, maxent_generate_features.

Examples

stack_path <- system.file("extdata", "stack_1_12_crop.rds",
                         package = "maxentcpp")
r <- terra::unwrap(readRDS(stack_path))
fs <- maxent_featured_space_from_rast(
    r,
    sample_indices = c(0L, 1L, 2L),
    feature_types  = c("linear", "quadratic")
)

Create a FeaturedSpace from a terra SpatRaster callback stream

Description

Same as maxent_featured_space_from_callback(), but also preserves the source SpatRaster S4 object for provider lifetime safety and can enable streaming-eval mode immediately.

Usage

maxent_featured_space_from_spatraster_callback(
  preserved_rast,
  rast_xptr,
  num_points,
  num_layers,
  layer_names,
  sample_indices,
  feature_types,
  n_thresholds,
  n_hinges,
  next_tile_fn,
  reset_fn,
  enable_streaming_eval = TRUE,
  use_cache = TRUE
)

Arguments

Value

External pointer to a FeaturedSpace object.

Get FeaturedSpace metadata

Description

Get FeaturedSpace metadata

Usage

maxent_featured_space_info(fs_ptr)

Arguments

Value

Named list with num_points, num_samples, num_features, density_normalizer, linear_predictor_normalizer, has_bias.

Train a MaxEnt Model

Description

Runs the sequential coordinate-ascent MaxEnt optimization on a FeaturedSpace.

Usage

maxent_fit(
  featured_space,
  max_iter = 500L,
  convergence = 1e-05,
  beta_multiplier = 1,
  min_deviation = 0.001
)

Arguments

Value

Named list with:

loss

Final regularized loss (scalar).

entropy

Shannon entropy of the trained distribution.

iterations

Number of training iterations completed.

converged

Logical: whether the convergence threshold was reached.

lambdas

Numeric vector of final lambda (weight) values.

Examples

n   <- 50L
idx <- c(5L, 15L, 25L, 35L, 45L)
env <- list(bio1 = runif(n), bio12 = runif(n))
feats <- maxent_generate_features(env, types = "linear")
fs  <- maxent_featured_space(n, idx, feats)
result <- maxent_fit(fs, max_iter = 100, convergence = 1e-5)
result$loss

Generate Features from Environmental Variable Data

Description

Automatically generates all configured feature types from one or more environmental variable vectors.

Usage

maxent_generate_features(
  data,
  types = c("linear", "quadratic", "product", "threshold", "hinge"),
  n_thresholds = 10L,
  n_hinges = 10L
)

Arguments

Value

Named list of external pointers to Feature C++ objects.

Examples

env_data <- list(
  temperature   = c(15, 20, 25, 18, 22),
  precipitation = c(100, 200, 150, 80, 300)
)
features <- maxent_generate_features(env_data, types = c("linear", "hinge"))
length(features)

Get entropy of a FeaturedSpace distribution

Description

Get entropy of a FeaturedSpace distribution

Usage

maxent_get_entropy(fs_ptr)

Arguments

Value

Shannon entropy (non-negative scalar).

Get current loss of a FeaturedSpace

Description

Get current loss of a FeaturedSpace

Usage

maxent_get_loss(fs_ptr)

Arguments

Value

Scalar loss value (negative log-likelihood).

Get current distribution weights from a FeaturedSpace

Description

Get current distribution weights from a FeaturedSpace

Usage

maxent_get_weights(fs_ptr)

Arguments

Value

Numeric vector of normalized weights (sums to 1).

Create a Grid Object

Description

Creates a raster grid for storing environmental variable data.

Usage

maxent_grid(dim, name = "", nodata_value = -9999)

Arguments

Value

Grid object (external pointer)

Examples

dim <- maxent_dimension(100, 100, -120, 35, 0.1)
grid <- maxent_grid(dim, "temperature")

Create a Grid from an R Matrix

Description

Builds a GridFloat from a numeric matrix and spatial parameters. NA values in the matrix are stored as the nodata value.

Usage

maxent_grid_from_matrix(mat, xll, yll, cellsize, nodata = -9999, name = "")

Arguments

Value

External pointer to a GridFloat C++ object.

Convert a terra SpatRaster to a maxentcpp GridFloat

Description

Converts a single-layer terra::SpatRaster into a maxentcpp GridFloat external pointer. The raster must have exactly one layer and square cells (equal x and y resolution).

Usage

maxent_grid_from_terra(r, name = NULL)

Arguments

Details

NA values in the raster are stored as NODATA (sentinel -9999).

Requires the terra package (listed in Suggests).

For the raster package, an equivalent workflow is:

  library(raster)
  r <- raster("bio1.tif")
  mat <- as.matrix(r)
  e <- extent(r)
  g <- maxent_grid_from_matrix(mat, xll = e@xmin, yll = e@ymin,
                               cellsize = res(r)[1],
                               name = names(r))

Value

External pointer to a GridFloat C++ object.

Examples

stack_path <- system.file("extdata", "stack_1_12_crop.rds",
                         package = "maxentcpp")
r <- terra::unwrap(readRDS(stack_path))
g <- maxent_grid_from_terra(r[[1]])
maxent_grid_info(g)

Get Grid Information

Description

Returns metadata about a GridFloat object read from a file.

Usage

maxent_grid_info(grid)

Arguments

Value

Named list with: nrows, ncols, xll, yll, cellsize, nodata, name, count_data.

Convert Grid to R Matrix

Description

Extracts the data from a GridFloat as an R numeric matrix. NODATA cells are converted to NA.

Usage

maxent_grid_to_matrix(grid)

Arguments

Value

Numeric matrix (nrows \times ncols).

Convert a maxentcpp GridFloat to a terra SpatRaster

Description

Creates a terra::SpatRaster from a maxentcpp GridFloat external pointer.

Usage

maxent_grid_to_terra(grid, crs = "EPSG:4326")

Arguments

Details

Requires the terra package (listed in Suggests).

For the raster package, an equivalent workflow is:

  library(raster)
  info <- maxent_grid_info(grid)
  mat  <- maxent_grid_to_matrix(grid)
  r <- raster(mat,
              xmn = info$xll,
              xmx = info$xll + info$ncols * info$cellsize,
              ymn = info$yll,
              ymx = info$yll + info$nrows * info$cellsize,
              crs = "+proj=longlat +datum=WGS84")

Value

A single-layer terra::SpatRaster.

Examples

stack_path <- system.file("extdata", "stack_1_12_crop.rds",
                         package = "maxentcpp")
r <- terra::unwrap(readRDS(stack_path))
g <- maxent_grid_from_terra(r[[1]])
r2 <- maxent_grid_to_terra(g)

Create a Hinge Feature

Description

Creates a piecewise-linear hinge feature.

Usage

maxent_hinge_feature(values, name, min_knot, max_knot, reverse = FALSE)

Arguments

Details

Forward hinge (reverse = FALSE): eval(i) = max(0, (values[i] - min_knot) / (max_knot - min_knot))

Reverse hinge (reverse = TRUE): eval(i) = max(0, (max_knot - values[i]) / (max_knot - min_knot))

Value

External pointer to a HingeFeature C++ object.

Examples

vals <- c(0, 5, 10, 3)
f <- maxent_hinge_feature(vals, "temperature_hinge", min_knot = 2, max_knot = 8)
maxent_feature_eval(f, 2)  # values[2] = 5 -> (5-2)/(8-2) = 0.5

Create a Layer Metadata Object

Description

Create a Layer Metadata Object

Usage

maxent_layer(name, type = "Continuous")

Arguments

Value

External pointer to a Layer C++ object.

Get Layer Metadata

Description

Get Layer Metadata

Usage

maxent_layer_info(layer)

Arguments

Value

Named list with name and type.

Extract Layer Name from a File Path

Description

Strips directory prefix and extension.

Usage

maxent_layer_name(path)

Arguments

Value

Character: layer name (e.g., "/data/bio1.asc" → "bio1").

Create a Linear Feature

Description

Creates a linear (normalized) feature that evaluates to (values[i] - min) / (max - min). Returns 0 when min == max.

Usage

maxent_linear_feature(values, name, min_val = NULL, max_val = NULL)

Arguments

Value

External pointer to a LinearFeature C++ object.

Examples

vals <- c(0, 5, 10, 3)
f <- maxent_linear_feature(vals, "temperature")
maxent_feature_eval(f, 1)  # index 1 (R) -> 0-based index 0

Load Model Lambdas from File

Description

Reads model coefficients from a .lambdas file and applies them to a FeaturedSpace that was created with the same features.

Usage

maxent_load_lambdas(featured_space, file)

Arguments

Value

Invisibly returns the FeaturedSpace external pointer (updated in-place).

Examples

maxent_load_lambdas(fs, tempfile(fileext = ".lambdas"))

Compute Log-Loss

Description

Computes the average cross-entropy log-loss from predictions at presence and absence sites.

Usage

maxent_logloss(presence, absence)

Arguments

Value

Average log-loss value (lower is better).

Examples

maxent_logloss(c(0.9, 0.8), c(0.1, 0.2))

Compute MESS (Multivariate Environmental Similarity Surface)

Description

Measures how similar each cell is to the training environment using the full distribution of reference values. Negative MESS values indicate novel (non-analog) environments.

Usage

maxent_mess(env_grids, reference_values, feature_names)

Arguments

Value

A named list with:

mess_grid

External pointer to Grid<float> with MESS values

mod_grid

External pointer to Grid<float> with Most Dissimilar Variable index (1-based)

Examples

result <- maxent_mess(list(g1, g2),
            list(temp_train_vals, precip_train_vals),
            c("temp", "precip"))
mess_mat <- maxent_grid_to_matrix(result$mess_grid)
mod_mat  <- maxent_grid_to_matrix(result$mod_grid)

Compute MESS from Min/Max Ranges

Description

Simplified MESS analysis using only the min/max of the reference data rather than the full distribution.

Usage

maxent_mess_range(env_grids, var_mins, var_maxs)

Arguments

Value

A named list with mess_grid and mod_grid (external pointers).

Compute Misclassification Rate

Description

Fraction of misclassified samples at threshold 0.5.

Usage

maxent_misclassification(presence, absence)

Arguments

Value

Misclassification rate in [0, 1].

Examples

maxent_misclassification(c(0.8, 0.9), c(0.1, 0.2))  # 0.0

Get Model Entropy

Description

Returns the Shannon entropy of the current MaxEnt distribution.

Usage

maxent_model_entropy(featured_space)

Arguments

Value

Scalar: Shannon entropy (non-negative).

Get Model Loss

Description

Returns the current (negative log-likelihood) loss of the model.

Usage

maxent_model_loss(featured_space)

Arguments

Value

Scalar: current loss value.

Get Model Distribution Weights

Description

Returns the normalized probability weights of the current MaxEnt distribution over the background points.

Usage

maxent_model_weights(featured_space)

Arguments

Value

Numeric vector of weights that sum to 1.

Compute Percent Contribution

Description

Computes variable contribution based on sum of absolute lambda values for features derived from each variable. Results sum to 100

Usage

maxent_percent_contribution(model, feature_names)

Arguments

Value

A data.frame with columns:

name

Variable name

contribution

Percent contribution

Examples

n   <- 50L
idx <- c(5L, 15L, 25L, 35L, 45L)
env <- list(temp = runif(n), precip = runif(n))
feats <- maxent_generate_features(env, types = "linear")
model <- maxent_featured_space(n, idx, feats)
maxent_fit(model, max_iter = 100, convergence = 1e-3)
contrib <- maxent_percent_contribution(model, c("temp", "precip"))
contrib  # data.frame with name and contribution

Compute Permutation Importance

Description

Measures how much each environmental variable contributes to model prediction quality by permuting each variable and measuring AUC drop. Results are normalised so that all importances sum to 100

Usage

maxent_permutation_importance(
  model,
  env_grids,
  feature_names,
  presence_rows,
  presence_cols,
  absence_rows,
  absence_cols,
  seed = 42L
)

Arguments

Value

A data.frame with columns:

name

Variable name

permutation_importance

Normalised importance (%)

Examples

imp <- maxent_permutation_importance(model, list(g1, g2),
         c("temp", "precip"),
         pres_rows, pres_cols, abs_rows, abs_cols)
imp  # data.frame with name and permutation_importance

Write Response Curve PNGs for All Variables

Description

Generates response curve plots for each environmental variable and saves them as PNG files, replicating density/ResponsePlot.java::makeplot(). A full-size PNG and an optional thumbnail are written for every variable.

Usage

maxent_plot_response_curves(
  model,
  env_grids,
  feature_names,
  output_dir,
  species,
  var_indices = NULL,
  n_steps = 100L,
  thumbnail = TRUE,
  write_dat = FALSE
)

Arguments

Value

Invisibly returns a named list of file paths written.

Examples

maxent_plot_response_curves(
  model, list(g1, g2), c("bio1", "bio12"),
  output_dir = tempdir(), species = "Sp1")

Write a Variable Importance Bar Chart PNG

Description

Creates a horizontal bar chart comparing percent contribution and permutation importance for each environmental variable, replicating density/Runner.java::makeJackknifePlots().

Usage

maxent_plot_variable_importance(
  contributions_df,
  perm_imp_df,
  species,
  output_dir
)

Arguments

Value

Invisibly returns the path to the PNG file.

Examples

maxent_plot_variable_importance(contrib, perm_imp,
  species = "Sp1", output_dir = tempdir())

Predict with a trained FeaturedSpace model

Description

Computes raw Gibbs distribution scores for new environmental data.

Usage

maxent_predict(fs_ptr, new_data)

Arguments

Value

Numeric vector of raw scores (unnormalized).

Predict with a Trained MaxEnt Model

Description

Computes raw Gibbs distribution scores for new environmental data, using the feature lambdas stored in the trained FeaturedSpace.

Usage

maxent_predict_model(featured_space, newdata)

Arguments

Value

Numeric vector of raw (unnormalized) prediction scores.

Examples

# After training, predict on 5 new points with 2 features each
newdata <- matrix(runif(10), nrow = 5, ncol = 2)
preds <- maxent_predict_model(fs, newdata)

Print Maxent Model Results

Description

Prints a summary of Maxent model performance metrics to the console, replicating the style of the dismo package's MaxEnt output. The report includes sample counts, training (and optionally test) evaluation statistics, and a ranked variable-contributions table.

Usage

maxent_print_results(
  species,
  eval_result,
  contributions_df,
  perm_imp_df,
  n_presence,
  n_background,
  test_eval_result = NULL,
  n_test = 0L,
  fit_result = NULL
)

Arguments

Value

Invisibly returns a named list with all reported metrics.

Examples

maxent_print_results(
  species          = "Sp1",
  eval_result      = maxent_evaluate(pres_preds, bg_preds),
  contributions_df = contrib,
  perm_imp_df      = perm_imp,
  n_presence       = length(pres_rows),
  n_background     = length(bg_rows))

Create a Product Feature

Description

Creates an interaction feature between two environmental variables: eval(i) = norm(values1[i]) * norm(values2[i]).

Usage

maxent_product_feature(
  values1,
  values2,
  name,
  min1 = NULL,
  max1 = NULL,
  min2 = NULL,
  max2 = NULL
)

Arguments

Value

External pointer to a ProductFeature C++ object.

Examples

temp <- c(0, 5, 10)
prec <- c(100, 200, 150)
f <- maxent_product_feature(temp, prec, "temp_x_prec")
maxent_feature_eval(f, 2)

Project Model onto Grids (Cloglog Output)

Description

Applies the Java Maxent cloglog transform to grid predictions:

cloglog = 1 - exp(-exp(H) \cdot raw)

Usage

maxent_project_cloglog(model, env_grids, feature_names)

Arguments

Details

where H is the model entropy and raw is the normalised probability. This matches the cloglog output of Java Maxent and dismo, and is the recommended output for reporting.

Value

External pointer to a Grid<float> with cloglog scores in [0, 1].

See Also

maxent_project_raw, maxent_project_logistic

Project Model onto Grids (Logistic Output)

Description

Applies the Java Maxent logistic transform to grid predictions:

logistic = \frac{exp(H) \cdot raw}{1 + exp(H) \cdot raw}

Usage

maxent_project_logistic(model, env_grids, feature_names)

Arguments

Details

where H is the model entropy and raw is the normalised probability. This matches the logistic output of Java Maxent and dismo.

Value

External pointer to a Grid<float> with logistic scores in [0, 1].

See Also

maxent_project_raw, maxent_project_cloglog

Project Model onto Grids (Raw Output)

Description

Produces Java Maxent "raw" scores for every grid cell:

raw = \frac{exp(lp - lpNorm)}{densityNorm}

Usage

maxent_project_raw(model, env_grids, feature_names)

Arguments

Details

This matches the raw output of the Java Maxent software and the dismo R package. See vignette("PREDICTION_SCALES") or docs/PREDICTION_SCALES.md for a full description of prediction scales.

Value

External pointer to a Grid<float> with Java raw scores.

See Also

maxent_project_cloglog, maxent_project_logistic

Create a Quadratic Feature

Description

Creates a quadratic feature that evaluates to linear_val^2 where linear_val = (values[i] - min) / (max - min).

Usage

maxent_quadratic_feature(values, name, min_val = NULL, max_val = NULL)

Arguments

Value

External pointer to a QuadraticFeature C++ object.

Examples

vals <- c(0, 5, 10)
f <- maxent_quadratic_feature(vals, "temperature_sq")
maxent_feature_eval(f, 2)  # evaluates at index 2 (1-based -> 0-based: 1)

Convert occurrence coordinates to 0-based stream indices

Description

Maps occurrence cell indices (as produced by terra::cellFromXY) into 0-based indices within the concatenated stream of finite (non-NA) background cells emitted by maxent_featured_space_from_rast.

Usage

maxent_raster_sample_indices(rast, cells)

Arguments

Value

Integer vector of 0-based indices within the finite-cell stream. Occurrence cells that fall on NA raster values (and therefore never appear in the stream) are silently dropped and a warning is emitted.

Read an ESRI ASCII Grid File

Description

Reads a .asc raster file into a GridFloat object.

Usage

maxent_read_asc(filename)

Arguments

Value

External pointer to a GridFloat C++ object.

Examples

g <- maxent_read_asc("bio1.asc")
info <- maxent_grid_info(g)
print(info)

Read a Grid File (Auto-Detect Format)

Description

Reads a raster grid file. The format is detected from the file extension. Currently supports .asc (ESRI ASCII Grid).

Usage

maxent_read_grid(filename)

Arguments

Value

External pointer to a GridFloat C++ object.

Read feature lambdas from a file

Description

Restores model coefficients from a .lambdas file. The FeaturedSpace must have been created with the same features (same names and order).

Usage

maxent_read_lambdas(fs_ptr, filename)

Arguments

Value

Called for side effects; returns invisibly.

Read Species Occurrence Data

Description

Reads species presence records from a CSV file or an R data.frame and converts them to row/column indices suitable for maxent_featured_space.

Usage

maxent_read_occurrences(
  file_or_df,
  dim,
  lon_col = "longitude",
  lat_col = "latitude",
  name_col = NULL
)

Arguments

Value

A named list with:

samples

List of Sample external pointers.

rows

Integer vector of row indices (0-based).

cols

Integer vector of column indices (0-based).

indices

Integer vector of 0-based flat indices (row * ncols + col), suitable for maxent_featured_space.

Examples

dim <- maxent_dimension(100, 100, -120, 35, 0.1)
occ <- data.frame(longitude = c(-118.5, -119.0),
                  latitude  = c(36.5, 37.0))
result <- maxent_read_occurrences(occ, dim)
result$indices  # 0-based flat indices for FeaturedSpace

Compute Marginal Response Curve

Description

Generates a response curve by varying one environmental variable from its minimum to maximum value while holding all other variables at their mean. Applies the Java Maxent cloglog transform, matching the output of Java Maxent and dismo:

cloglog = 1 - exp(-exp(H) \cdot raw)

Usage

maxent_response_curve(
  model,
  env_grids,
  feature_names,
  var_index,
  n_steps = 100L
)

Arguments

Value

A data.frame with columns:

value

Environmental variable value

prediction

Cloglog-transformed prediction

See Also

maxent_response_curve_fixed

Examples

curve <- maxent_response_curve(model, list(g1, g2),
           c("temp", "precip"), var_index = 0)
plot(curve$value, curve$prediction, type = "l")

Compute Response Curve with Fixed Values

Description

Like maxent_response_curve but the user supplies explicit fixed values for the non-target variables. Applies the Java Maxent cloglog transform, matching the output of Java Maxent and dismo:

cloglog = 1 - exp(-exp(H) \cdot raw)

Usage

maxent_response_curve_fixed(
  model,
  fixed_values,
  feature_names,
  var_index,
  var_min,
  var_max,
  n_steps = 100L
)

Arguments

Value

A data.frame with columns: value, prediction.

See Also

maxent_response_curve

Run a Complete Maxent Species Distribution Modelling Workflow

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:

1. Reads and validates occurrence records.

2. Samples background points.

3. Extracts environmental values and builds features.

4. Trains the Maxent model.

5. Projects the model onto the full landscape (cloglog output).

6. Evaluates model performance (AUC).

7. Computes percent contribution and permutation importance.

8. Writes all standard output files (lambdas, prediction PNG, response curve PNGs, omission CSV, sample-predictions CSV, and maxentResults.csv).

9. Prints a performance summary to the console.

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

Value

A named list with:

model

Trained FeaturedSpace external pointer.

fit_result

List returned by maxent_fit.

evaluation

List returned by maxent_evaluate.

contributions

Data.frame of percent contributions.

permutation_importance

Data.frame of permutation importances.

output_dir

The output directory used.

Examples

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

Create a MaxEnt Sample Object

Description

Creates a sample point representing a species occurrence location.

Usage

maxent_sample(lon, lat, name = "", dim = NULL)

Arguments

Value

Sample object (external pointer)

Examples

sample <- maxent_sample(lon = -118.5, lat = 36.5, name = "site1")

Save Model Lambdas to File

Description

Writes the trained model coefficients (lambdas) to a CSV file in the standard Maxent .lambdas format.

Usage

maxent_save_lambdas(featured_space, file)

Arguments

Value

Invisibly returns the output file path.

Examples

maxent_save_lambdas(fs, tempfile(fileext = ".lambdas"))

Train a MaxEnt Model with the Java-Equivalent Sequential Optimizer

Description

Runs the full density.Sequential optimizer ported from the original Java Maxent 3.4.4 on a FeaturedSpace. Unlike maxent_fit(), which uses the historical goodAlpha-only loop, this trainer reproduces the real Java optimizer: feature selection via deltaLossBound, Newton step with 1-D line search (searchAlpha), every-10-iteration doParallelUpdate with undo on loss-violating batch steps, and per-feature state tracking.

Usage

maxent_sequential_fit(
  featured_space,
  max_iter = 500L,
  convergence = 1e-05,
  beta_multiplier = 1,
  min_deviation = 0.001,
  parallel_update_frequency = 10L,
  disable_convergence_test = FALSE,
  trajectory_iterations = integer(0)
)

Arguments

Details

The lambda trajectory produced by this trainer matches the Java oracle's to 10^{-6} on \left\|\Delta\lambda\right\|_\infty at every checkpoint, on both the symmetric and asymmetric fixtures in maxentcppCompTest — see docs/ARCHITECTURE_xtensor_openmp.md and the Phase C baseline report for details.

Value

Named list with:

loss

Final regularized loss (scalar).

entropy

Shannon entropy of the trained distribution.

iterations

Number of training iterations completed.

converged

Logical: whether the convergence threshold was reached (always FALSE when disable_convergence_test = TRUE).

lambdas

Numeric vector of final lambda values.

trajectory

A data.frame with one row per captured checkpoint and columns iteration, loss, entropy, lambda_0, lambda_1, ..., lambda_{J-1}.

See Also

maxent_fit, maxent_featured_space.

Examples

fs  <- maxent_featured_space(100L, 90:99, list(f))
res <- maxent_sequential_fit(
    fs,
    max_iter                 = 500L,
    disable_convergence_test = TRUE,
    trajectory_iterations    = c(1L, 2L, 5L, 10L, 50L, 100L, 500L))
print(res$trajectory)

Train a FeaturedSpace with the Sequential optimizer (trajectory-capable)

Description

Runs the full density.Sequential optimizer ported from the original Java Maxent, with optional per-iteration trajectory snapshots. Unlike maxent_train() which uses a goodAlpha-only loop, this trainer reproduces the real Java optimizer's feature-selection (deltaLossBound), Newton step, 1-D line search, and every-10-iter doParallelUpdate with undo on loss-violating batch steps.

Usage

maxent_sequential_train(
  fs_ptr,
  max_iter = 500L,
  convergence = 1e-05,
  beta_multiplier = 1,
  min_deviation = 0.001,
  parallel_update_frequency = 10L,
  disable_convergence_test = FALSE,
  trajectory_iterations = as.integer(c())
)

Arguments

Value

Named list with elements: loss, entropy, iterations, converged, lambdas, and trajectory — a data.frame with columns iteration, loss, entropy, lambda_0, ..., lambda_{J-1} holding one row per requested checkpoint that was actually reached.

Set sample expectations for a FeaturedSpace

Description

Computes sample expectations and regularization deviations for each feature. Called automatically by maxent_train(), but exposed for advanced use.

Usage

maxent_set_sample_expectations(
  fs_ptr,
  beta_multiplier = 1,
  min_deviation = 0.001
)

Arguments

Value

Called for side effects; returns invisibly.

Enable or disable streaming-eval mode on a FeaturedSpace

Description

Enable or disable streaming-eval mode on a FeaturedSpace

Usage

maxent_set_streaming_eval(fs_ptr, enabled = TRUE)

Arguments

Value

Called for side effects; returns invisibly.

Get FeaturedSpace Information

Description

Returns basic metadata about a FeaturedSpace object.

Usage

maxent_space_info(featured_space)

Arguments

Value

Named list with: num_points, num_samples, num_features, density_normalizer, linear_predictor_normalizer.

Compute Mean Squared Error

Description

Presence sites contribute (1 - pred)^2, absence sites contribute pred^2.

Usage

maxent_square_error(presence, absence)

Arguments

Value

Mean squared error.

Examples

maxent_square_error(c(1.0, 1.0), c(0.0, 0.0))  # 0.0

Create a Threshold Feature

Description

Creates a binary step feature: eval(i) = 1 if values[i] > threshold, else 0.

Usage

maxent_threshold_feature(values, name, threshold)

Arguments

Value

External pointer to a ThresholdFeature C++ object.

Examples

vals <- c(1, 5, 10, 3)
f <- maxent_threshold_feature(vals, "temperature_threshold", threshold = 5)
maxent_feature_eval(f, 3)  # values[3] = 10 > 5 -> 1

Train a FeaturedSpace model

Description

Runs the sequential coordinate-ascent MaxEnt optimization.

Usage

maxent_train(
  fs_ptr,
  max_iter = 500L,
  convergence = 1e-05,
  beta_multiplier = 1,
  min_deviation = 0.001
)

Arguments

Value

Named list with elements: loss, entropy, iterations, converged, lambdas.

Train MaxEnt directly from a terra SpatRaster

Description

High-level convenience wrapper that builds a streaming FeaturedSpace from rast, maps occurrence locations to finite-stream sample indices, and trains with maxent_fit.

Usage

maxent_train_terra(
  rast,
  occurrences,
  lon_col = "longitude",
  lat_col = "latitude",
  feature_types = c("linear", "quadratic", "product", "threshold", "hinge"),
  n_thresholds = 10L,
  n_hinges = 10L,
  max_iter = 500L,
  convergence = 1e-05,
  beta_multiplier = 1,
  min_deviation = 0.001
)

Arguments

Value

A named list with training results plus model and sample_indices.

Compute Variable Ranges from Grids

Description

Scans all valid cells in the grids to determine the [min, max] range of each environmental variable.

Usage

maxent_variable_ranges(env_grids)

Arguments

Value

A data.frame with columns: min, max (one row per variable).

Write a Grid to ESRI ASCII Format

Description

Writes a GridFloat to a .asc file.

Usage

maxent_write_asc(grid, filename, scientific = TRUE)

Arguments

Value

Invisibly returns the output file path.

Examples

maxent_write_asc(g, tempfile(fileext = ".asc"))

Write feature lambdas to a file

Description

Saves the trained model coefficients in CSV format compatible with the original Java Maxent .lambdas file format.

Usage

maxent_write_lambdas(fs_ptr, filename)

Arguments

Value

Called for side effects; returns invisibly.

Write an Omission / Threshold CSV

Description

Computes cumulative predictions at all background + presence locations and derives nine standard threshold statistics, writing the result to <output_dir>/<species>_omission.csv. The output format mirrors density/Runner.java::writeCumulativeIndex().

Usage

maxent_write_omission_csv(
  model,
  env_grids,
  feature_names,
  presence_rows,
  presence_cols,
  output_dir,
  species,
  test_rows = NULL,
  test_cols = NULL
)

Arguments

Value

Invisibly returns the path to the written CSV file.

Examples

maxent_write_omission_csv(model, list(g1, g2), c("bio1", "bio12"),
  pres_rows, pres_cols, output_dir = tempdir(), species = "Sp1")

Write a Maxent Prediction Grid as a PNG Image

Description

Converts a GridFloat prediction grid to a colour PNG image using the canonical Maxent colour ramp (red = high, blue = low). Optionally overlays presence and test-point locations, and renders a small legend.

Usage

maxent_write_prediction_png(
  grid,
  filename,
  presence_rows = NULL,
  presence_cols = NULL,
  test_rows = NULL,
  test_cols = NULL,
  mode = "plain",
  legend = TRUE,
  width = 800L,
  height = 600L
)

Arguments

Value

Invisibly returns filename.

Examples

pred <- maxent_project_cloglog(model, list(g1, g2), c("bio1", "bio12"))
maxent_write_prediction_png(pred, tempfile(fileext = ".png"))

Write Sample Predictions CSV

Description

Computes model predictions at presence (and optionally test) locations and writes <output_dir>/<species>_samplePredictions.csv.

Usage

maxent_write_sample_predictions(
  model,
  env_grids,
  feature_names,
  presence_rows,
  presence_cols,
  output_dir,
  species,
  test_rows = NULL,
  test_cols = NULL
)

Arguments

Value

Invisibly returns the path to the written CSV.

Examples

maxent_write_sample_predictions(model, list(g1, g2), c("bio1", "bio12"),
  pres_rows, pres_cols, output_dir = tempdir(), species = "Sp1")

Print Sample Information

Description

Print Sample Information

Usage

## S3 method for class 'maxent_sample'
print(x, ...)

Arguments

Value

Invisibly returns x.

Project Model onto Grids (Java-compatible cloglog output)

Description

Applies the Java Maxent cloglog formula: cloglog_java = 1 - exp(-exp(H) * raw_java)

Usage

project_cloglog(fs_ptr, grid_ptrs, feature_names)

Arguments

Details

where H is the model entropy and raw_java is the normalised probability. This matches the cloglog output of Java Maxent and dismo.

Value

External pointer to a Grid<float> with Java cloglog scores in [0, 1].

Project Model onto Grids (Java-compatible logistic output)

Description

Applies the Java Maxent logistic formula: logistic_java = (exp(H) * raw_java) / (1 + exp(H) * raw_java)

Usage

project_logistic(fs_ptr, grid_ptrs, feature_names)

Arguments

Details

where H is the model entropy and raw_java is the normalised probability. This matches the logistic output of Java Maxent and dismo.

Value

External pointer to a Grid<float> with Java logistic scores in [0, 1].

Project Model onto Grids (Java-compatible raw output)

Description

Applies a trained FeaturedSpace model to produce Java Maxent "raw" scores: raw_java = exp(lp - lpNorm) / densityNorm

Usage

project_raw(fs_ptr, grid_ptrs, feature_names)

Arguments

Details

This matches the raw output of the Java Maxent software and the dismo R package.

Value

External pointer to a Grid<float> with Java raw scores.

Get feature value from a sample

Description

Get feature value from a sample

Usage

sample_get_feature(sample_ptr, feature_name, default_val = 0)

Arguments

Value

Feature value

Set feature value on a sample

Description

Set feature value on a sample

Usage

sample_set_feature(sample_ptr, feature_name, value)

Arguments

Value

Called for side effects; returns invisibly.

Set Grid from Matrix

Description

Populates grid with values from an R matrix.

Usage

set_grid_matrix(grid, mat)

Arguments

Value

Invisibly returns the grid object.