Spatial Mapping

struct SpatialTree{T<:BranchingProcessNode}

A structure to hold spatial positions for nodes in a branching process tree.

Fields

• tree: The original branching process tree.

• positions: Dictionary mapping nodes to their spatial positions (2D or 3D vectors).

• dim: Spatial dimension (2 or 3).

assign_spatial_positions(tree::BranchingProcessNode; 
                         dim::Int=2,
                         offset_scale::Float64=1.0,
                         root_position::Union{Nothing, Vector{Float64}}=nothing)

Assign spatial positions to all nodes in a branching process tree during a simulated growth process. At each splitting event, one child inherits the parent's position while other children are placed nearby with a random offset.

Arguments

• tree::BranchingProcessNode: The branching process tree to assign positions to.
• dim::Int=2: Spatial dimension (2 for 2D, 3 for 3D).
• offset_scale::Float64=1.0: Scale factor for the random offset distance.
• root_position::Union{Nothing, Vector{Float64}}=nothing: Initial position for the root node. Defaults to the origin.

Returns

A SpatialTree containing the original tree and a dictionary of positions.

assign_spatial_positions(sol::BranchingProcessSolution; kwargs...)

Assign spatial positions to a BranchingProcessSolution.

relax_positions!(spatial_tree::SpatialTree; 
                 iterations::Int=100,
                 min_distance::Float64=0.5,
                 step_size::Float64=0.1,
                 time::Union{Nothing, Float64}=nothing)

Apply force-directed relaxation to smooth density and avoid overlaps. Uses a simple repulsive force model where cells that are too close push each other apart.

Arguments

• spatial_tree::SpatialTree: The spatial tree with positions to relax.
• iterations::Int=100: Number of relaxation iterations.
• min_distance::Float64=0.5: Minimum allowed distance between cells.
• step_size::Float64=0.1: Step size for position updates (0 < step_size <= 1).
• time::Union{Nothing, Float64}=nothing: If specified, only relax positions of cells alive at this time. If nothing, relaxes leaf node positions.

Returns

The modified SpatialTree (positions are updated in place).

normalize_positions!(spatial_tree::SpatialTree;
                    bounds::Union{Nothing, Tuple}=nothing,
                    padding::Float64=0.1,
                    time::Union{Nothing, Float64}=nothing)

Normalize positions to fit within a bounding box for visualization.

Arguments

• spatial_tree::SpatialTree: The spatial tree with positions to normalize.
• bounds::Union{Nothing, Tuple}=nothing: Target bounding box as ((xmin, xmax), (ymin, ymax)) for 2D or ((xmin, xmax), (ymin, ymax), (zmin, zmax)) for 3D. Defaults to (0, 1) for each dimension.
• padding::Float64=0.1: Padding fraction to add around the positions (0 to 1).
• time::Union{Nothing, Float64}=nothing: If specified, normalize based on cells alive at this time. If nothing, normalizes based on leaf nodes.

Returns

The modified SpatialTree (positions are updated in place).

get_leaf_positions(spatial_tree::SpatialTree)

Get positions of all leaf nodes in the spatial tree.

Returns

A tuple of (nodes, positions) where positions is a matrix with each column being a node's position.

get_positions_at_time(spatial_tree::SpatialTree, t::Float64)

Get positions of all nodes alive at a specific time.

Returns

A tuple of (nodes, positions) where positions is a matrix with each column being a node's position.

get_values_at_positions(spatial_tree::SpatialTree;
                       time::Union{Nothing, Float64}=nothing,
                       variable_idx::Int=1)

Get solution values at spatial positions.

Arguments

• spatial_tree::SpatialTree: The spatial tree.
• time::Union{Nothing, Float64}=nothing: Time at which to get values. If nothing, uses the final time of each node.
• variable_idx::Int=1: Index of the variable to extract.

Returns

A tuple of (xcoords, ycoords, values) for 2D or (xcoords, ycoords, z_coords, values) for 3D.

create_spatial_layout(sol::BranchingProcessSolution;
                     dim::Int=2,
                     offset_scale::Float64=1.0,
                     relax::Bool=true,
                     relax_iterations::Int=100,
                     min_distance::Float64=0.5,
                     normalize::Bool=true,
                     bounds::Union{Nothing, Tuple}=nothing)

Create a complete spatial layout for a branching process solution. This is a convenience function that combines position assignment, relaxation, and normalization.

Arguments

• sol::BranchingProcessSolution: The branching process solution.
• dim::Int=2: Spatial dimension (2 or 3).
• offset_scale::Float64=1.0: Scale for random offsets during growth.
• relax::Bool=true: Whether to apply relaxation.
• relax_iterations::Int=100: Number of relaxation iterations.
• min_distance::Float64=0.5: Minimum distance for relaxation.
• normalize::Bool=true: Whether to normalize positions.
• bounds::Union{Nothing, Tuple}=nothing: Target bounds for normalization.

Returns

A SpatialTree with the complete spatial layout.

spatial_heatmap_data(spatial_tree::SpatialTree;
                    time::Union{Nothing, Float64}=nothing,
                    variable_idx::Int=1,
                    grid_size::Int=50,
                    interpolation::Symbol=:nearest)

Generate heatmap data for spatial visualization.

Arguments

• spatial_tree::SpatialTree: The spatial tree with positions.
• time::Union{Nothing, Float64}=nothing: Time at which to get values.
• variable_idx::Int=1: Index of the variable to visualize.
• grid_size::Int=50: Resolution of the output grid.
• interpolation::Symbol=:nearest: Interpolation method (:nearest or :linear).

Returns

A tuple of (xgrid, ygrid, value_grid) for use with heatmap plotting.

get_time_series_frames(spatial_tree::SpatialTree, sol::BranchingProcessSolution;
                      variable_idx::Int=1,
                      n_frames::Int=50,
                      grid_size::Int=50)

Generate a series of heatmap frames for creating an animation of the branching process over time.

Arguments

• spatial_tree::SpatialTree: The spatial tree with positions.
• sol::BranchingProcessSolution: The original solution for time bounds.
• variable_idx::Int=1: Index of the variable to visualize.
• n_frames::Int=50: Number of frames to generate.
• grid_size::Int=50: Resolution of each frame's grid.

Returns

A tuple of (times, frames) where times is a vector of time points and frames is a vector of (xgrid, ygrid, value_grid) tuples.

_random_direction(dim::Int)

Generate a random unit direction vector in the specified dimension.

_nodes_alive_at_time(tree::BranchingProcessNode, t::Float64)

Get all nodes that are "alive" at time t (their solution spans time t).