spax Package Function Naming Convention

library(spax)

SPAX Package Development Guidelines

Function Hierarchy and Naming Conventions

High-Level Functions (`spax_*`)

Purpose: Complete workflows that users interact with directly
Naming: Must start with spax_
Examples: spax_e2sfca(), spax_ifca()
Input Requirements: Should accept primitive inputs (demand, supply, distance rasters)
Documentation: Must include complete examples in roxygen comments

Semi-High Level Functions (`comp_*`)

Purpose: Complex computational operations that can work independently
Naming: Must start with comp_
Examples: comp_iterative(), comp_iterative_fast()
Note: These functions often implement core algorithms

Middle-Level Operations

Four categories of operational functions:

Gather Operations (gather_*)
- Purpose: Dimension reduction (e.g., raster stack → vector)
- Examples: gather_demand(), gather_weighted()
Spread Operations (spread_*)
- Purpose: Dimension expansion (e.g., vector → raster stack)
- Examples: spread_access(), spread_weighted()
Calculate Operations (calc_*)
- Purpose: Layer-wise operations maintaining dimensions
- Examples: calc_decay(), calc_normalize(), calc_choice()
Transform Operations (transform_*)
- Purpose: Surface-wide transformations
- Examples: transform_pmf()

Low-Level Functions

Internal functions not exported in the NAMESPACE:

Validation Functions (.chck_*)
- Purpose: Input validation
- Examples: .chck_calc_choice(), .chck_sample_pmf()
Helper Functions (.help_*)
- Purpose: Utility functions used by higher-level functions
- Examples: .help_prep_facilities(), .help_gen_sample_size()
Core Functions (.*_core)
- Purpose: Main computational logic for complex operations
- Examples: .sample_pmf_core_indp(), .sample_pmf_core_evlv()

Function Structure Guidelines

Standard Function Template

function_name <- function(
    required_param,
    optional_param = default_value,
    ...,
    snap = FALSE
) {
    # 1. Input Validation (skip if snap = TRUE)
    if (!snap) {
        .chck_function_name(required_param, optional_param)
    }

    # 2. Pre-processing
    processed_data <- .help_process_data(required_param)

    # 3. Main Computation
    result <- .function_name_core(processed_data, ...)

    # 4. Post-processing (skip if snap = TRUE)
    if (!snap) {
        result <- .help_post_process(result)
    }

    return(result)
}

The `snap` Parameter

Purpose: Performance optimization for internal use
Default: Always FALSE
When TRUE:
- Skips input validation
- Skips non-essential processing
- Assumes inputs are correctly formatted
- May skip naming/attribute assignment
Usage: Only set TRUE when called from within other package functions where inputs have already been validated

Documentation Requirements

Roxygen Headers

#' @title Function Title
#' @description Detailed description
#' @param snap Logical; if TRUE enables fast computation mode with minimal validation
#' @export

Internal Function Documentation

#' @keywords internal
.internal_function <- function() {

File Organization

All R files must be in the R/ directory (no subdirectories). Use file naming conventions:

00-utils.R: Helper functions
01-core.R: Core computations
02-operations.R: Middle-level operations
03-compute.R: Semi-high level functions
04-spax.R: High-level functions

Error Handling

Use stop() for critical errors in validation
Use warning() for non-critical issues
Use message() sparingly for important information

Performance Considerations

Always include the snap parameter for functions that might be called repeatedly
Use terra functions instead of raster when possible
Avoid loops when vectorized operations are possible
Consider parallel processing for computationally intensive operations

Testing Requirements

Each function should have corresponding tests in tests/testthat/
Include tests for both normal and snap=TRUE modes
Test error conditions and edge cases
Include performance benchmarks for critical functions

Development Workflow

Creating New Functions
- Start with the function template
- Add validation function if needed
- Implement core logic
- Add documentation
- Add tests
Modifying Existing Functions
- Maintain backward compatibility
- Update documentation
- Update tests
- Update vignettes if behavior changes
Deprecating Functions
- Use .Deprecated() function
- Maintain old function for at least one version
- Update documentation to point to new function
- Update vignettes to use new function

Version Control Guidelines

Commit Messages
- Start with type: feat, fix, docs, style, refactor, test, chore
- Include scope in parentheses
- Example: feat(calc): add new decay function
Branches
- main: Stable release
- develop: Development version
- feature/*: New features
- fix/*: Bug fixes

Documentation Updates

When adding or modifying functions: 1. Update relevant vignettes 2. Update README.md if needed 3. Update NAMESPACE 4. Run roxygen2 to update documentation 5. Update NEWS.md with changes

Complete Function Catalog

Current Name	/new name	Level	Subcategory	Notes
parameter_tuning.R	depricated	-	-
spread_functions.R	-	-	-	-
`weighted_spread()`	→ `spread_weighted()`	Middle	Spread	General spreading function
`.spread_single()`	→ `.spread_core()`	Low	Internal	Single value spreading
`spread_access()`	✓	Middle	Spread	Access distribution
compute_choice.R	should change to check and main
`.compute_choice_core()`	→ `deprec`	Low	Core	will re write a fn - so the computation will be in a main fn while the check is in another
`compute_choice()`	→ `calc_choice`	mid	mid	Choice probability calculation
	→ `.chck_calc_choice`	Low	check	validation for calc choice
compute_huff_weights.R	-	-	-	-
`compute_huff_weights()`	→ `deprec`	Semi-High	Compute	Huff model weights
compute_pmf.R	-	-	-	-
`compute_pmf()`	→ `transform_pmf()`	Middle* independent	Transform	PMF conversion
decay_functions.R	-	-	-	-
`compute_weights()`	→ `calc_decay()`	Middle	Calc	Calc decay weight
`.gaussian_weights()`		Low	Internal	Gaussian decay
`.exponential_weights()`		Low	Internal	Exponential decay
`.power_weights()`		Low	Internal	Power decay
`.inverse_weights()`		Low	Internal	Inverse decay
`.binary_weights()`		Low	Internal	Binary decay
gather_functions.R	-	-	-	-
`weighted_gather()`	→ `gather_weighted()`	Middle	Gather	General gathering
`gather_demand()`	✓	Middle	Gather	Demand aggregation
iterative_chain.R	-	-	-	-
`preprocess_facilities()`	→ `.help_prep_facilities()`	Low	Helper	Facility data preparation
`reintegrate_facilities()`	→ `.help_add_0facilities()`	Low	Helper	Facility reintegration
`update_facility_names()`	→ depricated	Low	Helper	Name updating
`run_iterative_core_fast()`	→ `compute_iterative_fast()`	semi-high *snap	Core	Fast iteration implementation
`run_iterative_core()`	→ `compute_iterative()`	semi-high	Core	Full iteration implementation
`spax_ifca()`		High	Main	Iterative FCA analysis
measure_access.R	-	-	-	-
`measure_access()`	→ `compute_access()`	Semi-High	Compute	General accessibility
`compute_2sfca()`	→ `spax_e2sfca()`	High	Compute	2SFCA implementation
normalize_functions.R	-	-	-	-
`.normalize_core()`	→ `depricate`	Low	Core - will move to validate + main than main + core	Core normalization
`normalize_weights()`	→ `calc_normalize()`	Middle	Calculate	Weight normalization
	→ `.chck_calc_normalize()`	low	checker
sample_pmf.R	-	-	-	-
`sample_pmf()`	ok	semi-high	Transform	PMF sampling
`.validate_sample_pmf_inputs()`	→ `.chck_sample_pmf()`	Low	Check	Input validation
`.check_and_convert_pmf()`	→ `.ckck_n_convert_pmf()`	Low	Check	PMF validation
`.compute_sample_sizes()`	→ `.help_gen_sample_size()`	Low	Helper	Sample size computation
`.generate_spatial_samples()`	→ .`sample_pmf_core_indp()`	mid	Core	Sample generation
`est_new_samples()`	→ `.help_est_new_sample()`	Low	Helper	Sample estimation
`.generate_evolve_samples()`	→ .`sample_pmf_core_evlv()`	Low	Core	Evolution samples

Missing Functions (Suggested Additions)

Function Name	Level	Subcategory	Purpose
`spax_2sfca()`	High	Main	Complete 2SFCA workflow
`spax_montecarlo()`	High	Main	Monte Carlo analysis
`summarize_accessibility()`	Middle	Summarize	Accessibility statistics
`validate_inputs_check()`	Low	Check	General input validation
`plot_accessibility()`	Middle	Visualize	Standard accessibility plots

Would you like to: 1. Review specific function groups in detail? 2. Discuss the suggested name changes? 3. Prioritize which missing functions to implement first?