tacco.tools.annotation_coordinate

annotation_coordinate(adata, annotation_key, sample_key=None, distance_key=None, position_key=('x', 'y'), result_key=None, critical_neighbourhood_size=100, reference_key=None, max_distance=None, sparse=True, delta_distance=None, verbose=1, **kw_args)[source]

Calculates a distance-like quantity from an annotation in space.

Parameters:

  • adata – A AnnData.

  • annotation_key – The .obs or .obsm key to calculate distances from. For categorical .obs keys and for .obsm keys, the distances from all components are calculated. The numerical value of the annotation is used as a weight for distance calculation, see critical_neighbourhood_size.

  • sample_key – A categorical sample annotation. The calculation is performed separately per sample. If None, all observations are assumed to be on the same sample.

  • distance_key – The .obsp key containing a precomputed distance matrix to use. If None, the distances are computed on the fly with the positions found in position_key. Otherwise position_key is ignored.

  • position_key – The .obsm key or array-like of .obs keys with the position space coordinates

  • result_key – The .obsm key to contain the result. If None, the result is returned as a DataFrame.

  • critical_neighbourhood_size – The aggregated weight of a observations within a certain distance in order to call this distance THE distance (see reference_key). The weight used here is determined by numerical annotation values.

  • reference_key – The .obs key to use as reference weights (i.e. the maximum weight possible per observation) for neighbourhood size distance correction. If None, use 1 per observation, which makes sense if the annotation is categorical or fractional annotations which should sum to 1. If False, dont perform the correction.

  • max_distance – The maximum distance to use. If None or np.inf, uses the maximum distance in the data (if there are multiple samples, then only the first sample is used). If the distance matrix is not precomputed (see distance_key), None and np.inf result in dense distance computation (which can be infeasible for larger datasets).

  • sparse – Whether to calculate a sparse or dense distance matrix, if it is not precomputed. If None, this is determined by the value of max_distance.

  • delta_distance – The width in distance for distance discretization. If None, takes max_distance/100.

  • verbose – Level of verbosity, with 0 (no output), 1 (some output), …

  • **kw_args – Additional keyword arguments are forwarded to on-the-fly distance calculation with distance_matrix() if necessary.

Returns:

Depending on result_key returns either the updated input adata or the result directly as DataFrame.