Grouped Correlations

Incremental Pearson correlations, one per series, between a fixed set of per-point values and a mutable set of per-point values, where the points are partitioned into consecutive groups. Replacing the variable values of a single group cheaply updates every per-series correlation. A per-point is_active mask filters which points contribute to the correlations - inactive points are excluded from every sum (both the fixed totals and the variable/product sums) and from the effective n used in the correlation. The mask can be supplied at build, and a new mask for a single group can be passed on a replace_group! / mean_correlation_if_group_replaced call.

Incremental Pearson correlations between a fixed and a variable value per point, for each of several series, where the points are partitioned into n_groups consecutive groups. Values rows are points and columns are series. Points are laid out such that the points in each group are in consecutive rows. A per-point is_active mask filters which points contribute - inactive points are excluded from every sum and from the effective n used in the correlation. The per- group active counts are tracked so that mask changes during replace_group! cheaply update both the fixed-side totals (via a transition delta) and the effective n .

correlation_per_series!(
    grouped::GroupedSeriesCorrelations,
    correlation_per_series::AbstractVector{<:AbstractFloat},
)::AbstractVector{<:AbstractFloat}

Fill correlation_per_series with the current per-series Pearson correlation between the fixed and variable values (over the active points), and return it. Undefined cases (zero variance, or fewer than 2 active points) get 0.

mean_correlation(grouped::GroupedSeriesCorrelations)::Float64

The mean over all series of the current per-series correlation (undefined cases counted as 0). Allocation-free.

mean_correlation_if_group_replaced(
    grouped::GroupedSeriesCorrelations,
    group_index::Integer,
    variable_per_point_per_series::AbstractMatrix{<:Real},
    [is_active_per_group_point::AbstractVector{Bool}],
)::Float64

The mean per-series correlation that would result if group group_index 's variable values were replaced by variable_per_point_per_series (a group_size × n_series matrix in the group's point order), without committing the change. The values matrix is indexed by all group_size points (entries for inactive points are still passed - they are multiplied out by the mask). If is_active_per_group_point is supplied (a group_size -vector of Bool ), the group's mask is also tentatively replaced and the fixed-side totals adjusted for the activity transitions; otherwise the current mask is kept. Allocation-free and side-effect-free, so it is safe to call concurrently on a shared grouped .

mean_correlation_if_group_replaced(
    grouped::GroupedSeriesCorrelations,
    group_index::Integer,
    variable_per_source_per_series_position::AbstractMatrix{<:Real},
    is_active_per_source::AbstractVector{Bool},
    source_index_per_point::AbstractVector{<:Integer},
    series_position_per_series::AbstractVector{<:Integer},
)::Float64

Indirect-gather variant: like the 4-arg mean_correlation_if_group_replaced with a mask, but the new variable values and activity flags live in variable_per_source_per_series_position and is_active_per_source indexed by an upstream "source" axis (e.g. cell-position in a calling block) rather than in a freshly materialized per-group layout. source_index_per_point[p] gives the source index for point p in the group's canonical layout; series_position_per_series[s] gives the column position in variable_per_source_per_series_position for the group's series s . Lets the caller skip materializing a (group_size × n_series) scratch matrix - the gather happens inside @turbo via the indirection vectors. Allocation-free. Like the direct variant, does not mutate grouped .

replace_group!(
    grouped::GroupedSeriesCorrelations,
    group_index::Integer,
    variable_per_point_per_series::AbstractMatrix{<:Real},
    [is_active_per_group_point::AbstractVector{Bool}],
)::Nothing

Commit new variable values for group group_index (a group_size × n_series matrix in the group's point order), updating the kept sums in place. If is_active_per_group_point is supplied (a group_size -vector of Bool ), the group's mask is also updated and the fixed-side totals are adjusted for the activity transitions; otherwise the current mask is kept. Does not compute correlations - call mean_correlation or correlation_per_series! once after committing all the changed groups. Allocation-free; not safe to call concurrently with itself or with queries on the same grouped .

replace_group!(
    grouped::GroupedSeriesCorrelations,
    group_index::Integer,
    variable_per_source_per_series_position::AbstractMatrix{<:Real},
    is_active_per_source::AbstractVector{Bool},
    source_index_per_point::AbstractVector{<:Integer},
    series_position_per_series::AbstractVector{<:Integer},
)::Nothing

Indirect-gather variant of the 5-arg replace_group! with a mask: the new variable values and activity flags live in variable_per_source_per_series_position and is_active_per_source indexed by an upstream source axis (e.g. cell- position in a calling block) rather than in a freshly materialized per-group layout. source_index_per_point[p] gives the source index for point p in the group's canonical layout; series_position_per_series[s] gives the column position in variable_per_source_per_series_position for the group's series s . Lets the caller skip materializing a (group_size × n_series) scratch matrix - the gather happens inside @turbo via the indirection vectors. Same mutation contract as the direct variant.