sparse_adjust_towards_aggregates

caf.distribute.iterative_proportional_fitting.sparse_adjust_towards_aggregates(mat, target_marginals, target_dimensions, convergence_fn)

Adjust a matrix towards aggregate targets.

Uses target_aggregates and target_dimensions to calculate adjustment factors across each of the dimensions, brining mat closer to the targets.

Parameters:

• mat (COO) – The starting matrix that should be adjusted

• target_marginals (list[COO]) – A list of the aggregates to adjust matrix towards. Aggregates are the target values to aim for when aggregating across one or several other axis. Directly corresponds to target_dimensions.

• target_dimensions (list[list[int]]) – A list of target dimensions for each aggregate. Each target dimension lists the axes that should be preserved when calculating the achieved aggregates for the corresponding target_marginals. Another way to look at this is a list of the numpy axis which should NOT be summed from mat when calculating the achieved marginals.

• convergence_fn (Callable[[Collection[ndarray], Collection[ndarray]], float]) – The function that should be called to calculate the convergence of mat after all target_marginals adjustments have been made. If a callable is given it must take the form: fn(targets: list[np.ndarray], achieved: list[np.ndarray])

Returns:

• adjusted_mat – The input mat, adjusted once for each aggregate towards the target_marginals

• convergence – A float describing the convergence of adjusted_mat to target_marginals. Usually lower is better, but that depends on the exact convergence_fn in use.

Return type:

tuple[ndarray, float]