\value documentation
describing the output’s class, structure, and meaning.\dontrun{} wrappers have been removed. Slower examples are
now wrapped in \donttest{} as appropriate.The wizard function Euclidify was added to run all the
workflow needed to get the main output automatically.
create_topolow_map() is now deprecated in favor of
euclidean_embedding(). The old function will be removed in
version 3.0.0.
distance_matrix –>
dissimilarity_matrixcreate_topolow_map() –>
euclidean_embedding()initial_parameter_optimization():
Parameter distance_matrix renamed to
dissimilarity_matrix
distance_matrix = your_matrix with
dissimilarity_matrix = your_matrixrun_adaptive_sampling(): Parameter
distance_matrix renamed to
dissimilarity_matrix
distance_matrix = your_matrix with
dissimilarity_matrix = your_matrixadaptive_MC_sampling():
distance_matrix renamed to
dissimilarity_matrixbatch_size from
adaptive_MC_sampling(); its value had no effect in the
processes anywaynum_parallel_jobs from
run_adaptive_sampling; set max_cores to define
the number of cores and parallel jobsdistance_matrix = your_matrix with
dissimilarity_matrix = your_matrix and remove
batch_size argumentscreate_cv_folds(): Parameter names and
return structure changed
truth_matrix –>
dissimilarity_matrix, no_noise_truth –>
ground_truth_matrix$truth, $train) instead of indexed
elementsresult[[1]][[1]] to result[[1]]$truth,
result[[1]][[2]] to result[[1]]$traintake_log parameter in clean_data() is
deprecated
analyze_network_structure(): Parameter
distance_matrix renamed to
dissimilarity_matrix for consistency with other
functionscalculate_diagnostics(): Return class
changed from topolow_amcs_diagnostics to
topolow_diagnostics for naming consistencyplot_network_structure(): Removed
aesthetic_config and layout_config parameters
width,
height, dpi parametersscatterplot_fitted_vs_true():
Parameter names updated for consistency
distance_matrix –>
dissimilarity_matrix, p_dist_mat –>
p_dissimilarity_matsave_plot changed
from TRUE to FALSElinewidth instead
of deprecated sizeerror_calculator_comparison():
Parameter names changed for consistency
p_dist_mat –>
predicted_dissimilaritiestruth_matrix –>
true_dissimilaritiesinput_matrix –> input_dissimilarities
(now optional, defaults to NULL)calculate_prediction_interval():
Parameter names changed for consistency
distance_matrix –>
dissimilarity_matrixp_dist_mat –>
predicted_dissimilarity_matrixlong_to_matrix was renamed to
titers_list_to_matrix since it is specific to viral titer
data processing.process_antigenic_data accepts a data frame as
input, instead of the previous form of a file path.process_antigenic_data, is_titer became
is_similarity for clearity for broader audience. Parameter
id_prefix was removed.euclidean_embedding() function with enhanced
performance and features:
parameter_sensitivity function to use modern
ggplot2 syntaxsize parameter with
linewidth in plotscreate_cv_folds()input_dissimilarities parameter now optional in
error_calculator_comparison()initial_parameter_optimization saves/returns the
parameters in log scale, consistent with other functioncreate_topolow_map() deprecated, issues
warningcreate_topolow_map() will be
removedTo update your code:
# Old (deprecated):
result <- create_topolow_map(distance_matrix = my_matrix,
# ... other parameters
)
# New (recommended):
result <- euclidean_embedding(dissimilarity_matrix = my_matrix, # parameter name changed
# ... other parameters (unchanged)
)Included figures in the vignette.
create_diagnostic_plots() is deprecated in favor of
plot_mcmc_diagnostics(), so that every plotting function
shares the plot_* prefix. The old function still works and
warns; it will be removed in version 3.0.0.
create_diagnostic_plots(...) –>
plot_mcmc_diagnostics(...)res –>
dpiMajor Feature: Added the optional
opt_subsample parameter to key optimization functions,
enabling efficient parameter optimization on large datasets while
maintaining final embedding quality. Parameter optimization still works
reliably with subsampling, because likelihoods of samples of the same
size are comparable, allowing us to choose the optimal parameter
values.
New Functions:
check_matrix_connectivity(): Validates that a
dissimilarity matrix forms a connected graphsubsample_dissimilarity_matrix(): Creates random
subsamples with automatic connectivity validation and adaptive size
adjustmentsanity_check_subsample(): Validates subsample
suitability for cross-validationprune_sparse_matrix(): Prunes sparse dissimilarity
matrices to a well-connected subsetplot_mcmc_diagnostics(): Replacement for
create_diagnostic_plots() (see Deprecations)plot_ll_improvement(),
plot_performance_trace(): Diagnostics for the parameter
searchplot_euclidify_diagnostics(),
create_diagnostic_report(): Diagnostics for
Euclidify() outputEnhanced Functions:
initial_parameter_optimization(): Now accepts
opt_subsample parameterrun_adaptive_sampling(): Now accepts
opt_subsample parameteradaptive_MC_sampling(): Now accepts
opt_subsample parameter (internal)Euclidify(): Now accepts opt_subsample
parameterWhen opt_subsample is specified:
The opt_subsample parameter is optional (default: NULL =
use full data).
opt_subsample = NULL)opt_subsample = 200-500opt_subsample >= folds for reliable
cross-validationinitial_parameter_optimization() gained an
epochs argument (default: 1). With more than one epoch the
search runs as a simple evolutionary strategy:
num_samples points by Latin hypercube sampling
within the current ranges.opt_subsample is set, each evaluation uses its own
random subsample.0.75 * min(survivors) through
1.25 * max(survivors). This lets the search drift toward
and zoom in on promising regions.gridExtra is a required import now.initial_parameter_optimization() (and therefore
Euclidify()) could fail on Windows with
invalid connection whenever the parameter search ran in
more than one batch. A cluster shutdown handler was registered per
batch, and all of them referred to the last cluster, so it was stopped
repeatedly while the earlier clusters leaked. Each batch’s cluster is
now stopped as soon as that batch finishes. The failure was reliably
triggered by max_cores = 2, which is the configuration used
on CRAN check machines.R/adaptive_sampling.R is now handled by the package’s
extract_numeric_values() function.run_adaptive_sampling() no longer sleeps for a fixed
1.5 seconds on every call. Two Sys.sleep() calls guarded
file visibility on networked filesystems (NFS, Lustre); they now poll
for the expected state instead, so the wait is effectively free on a
local filesystem while networked ones still get up to 5 seconds. This
removed about a second from every Euclidify() run and has
no effect on results.*_range arguments of
Euclidify() are a starting range for the search,
not a hard bound. Initial sampling draws inside the range, but
adaptive refinement samples from a kernel density estimate of the best
parameter sets found so far, which can propose values outside it. So
ndim_range = c(3, 6) does not guarantee a 3- to
6-dimensional result; only the sanity limits (for example
1 <= ndim <= 50) are enforced. This behaviour is
unchanged from earlier versions and is now documented, in a new section
of ?Euclidify. Use euclidean_embedding() with
an explicit ndim when a hard cap is required.This is the first release of topolow containing compiled
code. The core optimization loop of
euclidean_embedding() has been rewritten in C++ using Rcpp,
which speeds up the embedding substantially, most visibly on larger
matrices. The remaining R-level loops in that function were replaced
with vectorized operations.
New parameter for
euclidean_embedding():
convergence_check_freq: How often, in iterations, to
test for convergence (default: 3). Larger values reduce the bookkeeping
overhead; smaller values stop more promptly.Implementation details:
std::mt19937),
which is what lets the configuration escape local optimaReturn value enhancement: the
convergence field of the returned topolow
object now includes:
achieved: whether convergence was reachederror: final MAE on active constraintsfinal_k: final spring constant after coolingDependencies: added Rcpp to
LinkingTo (compile-time only; no new runtime dependency).
The backend is Rcpp-only and links no BLAS or LAPACK routines, so no
src/Makevars is required on any platform.
std::random_device, independent of R’s RNG.
set.seed() fixes the starting configuration (drawn with
stats::runif()) but not the sweep order, so repeated runs
differ slightly. The R implementation in 2.0.1 shuffled the sweep order
in the same way.result$convergence$error) is now
accumulated in package code rather than by a BLAS routine, so it can
differ in the last representable digit from earlier development builds.
This is far below the run-to-run variation produced by the shuffle, and
it makes the value consistent across platforms, which it previously was
not. Embedded positions are unaffected.Reproducibility section of
?euclidean_embedding for what is and is not seeded, and for
how to obtain a single canonical map.euclidean_embedding() will work
without modificationEuclidify(), parameter optimization, etc.)