scanpy.tl.draw_graph#

scanpy.tl.draw_graph(adata, layout='fa', *, init_pos=None, root=None, rng=None, n_jobs=None, use=None, out=False, adjacency=None, neighbors_key=None, obsp=None, copy=False, key_added_ext=None, **kwds)[source]#

Force-directed graph drawing [Chippada, 2018, Islam et al., 2011, Jacomy et al., 2014].

An alternative to tSNE that often preserves the topology of the data better. This requires running neighbors(), first.

The default layout (‘fa’, ForceAtlas2, Jacomy et al. [2014]) uses the package fa2-modified [Chippada, 2018], which can be installed via pip install fa2-modified.

Force-directed graph drawing describes a class of long-established algorithms for visualizing graphs. It was suggested for visualizing single-cell data by Islam et al. [2011]. Many other layouts as implemented in igraph [Csárdi and Nepusz, 2006] are available. Similar approaches have been used by Zunder et al. [2015] or Weinreb et al. [2017].

Array type support#

Array type

supported

… experimentally in dask Array

numpy.ndarray

✅

❌

scipy.sparse.{csr,csc}_{array,matrix}

✅

❌
Parameters:
adata AnnData

Annotated data matrix.

layout Literal['fr', 'drl', 'kk', 'grid_fr', 'lgl', 'rt', 'rt_circular', 'fa'] (default: 'fa')

‘fa’ (ForceAtlas2) or any valid igraph layout. Of particular interest are ‘fr’ (Fruchterman Reingold), ‘grid_fr’ (Grid Fruchterman Reingold, faster than ‘fr’), ‘kk’ (Kamadi Kawai’, slower than ‘fr’), ‘lgl’ (Large Graph, very fast), ‘drl’ (Distributed Recursive Layout, pretty fast) and ‘rt’ (Reingold Tilford tree layout).

root int | None (default: None)

Root for tree layouts.

rng int | integer | Sequence[int] | SeedSequence | Generator | BitGenerator | None (default: None)

Random number generation to control stochasticity.

If a type:SeedLike value, it’s used to seed a new random number generator; If a numpy.random.Generator, rng’s state will be directly advanced; If None, a non-reproducible random number generator is used. See numpy.random.default_rng() for more details.

The default value matches legacy scanpy behavior and will change to None in scanpy 2.0.

Applies to layouts with random initialization like 'fr'.

init_pos MultiAcc | str | bool | None (default: None)

'paga'/True, None/False, or a 2d .obsm entry, e.g. A.obsm['umap']. Other strs are resolve()d if scanpy.settings.preset is ScanpyV2Preview (e.g. 'obsm.umap'), otherwise they are keys of .obsm. Use precomputed coordinates for initialization. If False/None (the default), initialize randomly.

use GraphAcc | str | None (default: None)

The neighborhood graph (connectivities) to use, e.g. A.obsp['k'] after sc.pp.neighbors(adata, out=A.obsp['k']), or any other graph. strs are resolve()d, e.g. 'obsp.k'. If None, the one neighbors() wrote by default.

out MultiAcc | str | bool (default: False)

Where to write the embedding. Given by an accessor, e.g. A.obsm['fa']. strs are anndata.acc.AdAcc.resolve()d. Accompanying uns entries are stored under the same key. If True, the embedding is returned instead of written. If False, it is written to .obsm['X_draw_graph_{layout}'] and .uns['draw_graph'] (.obsm['graph_{layout}'] and .uns['graph_{layout}'] if scanpy.settings.preset is ScanpyV2Preview).

adjacency csr_array | csc_array | csr_matrix | csc_matrix | None (default: None)

Deprecated since version 1.13.0: Store the graph in .obsp and pass use=A.obsp[...] instead.

Sparse adjacency matrix of the graph, defaults to neighbors connectivities.

neighbors_key str | None (default: None)

Deprecated since version 1.13.0: Use use instead, e.g. use=A.obsp['k_connectivities'] for neighbors_key='k'.

If not specified, draw_graph looks at .obsp['connectivities'] for connectivities (default storage place for pp.neighbors). If specified, draw_graph looks at .obsp[.uns[neighbors_key]['connectivities_key']] for connectivities.

obsp str | None (default: None)

Deprecated since version 1.13.0: Use use=A.obsp[...] instead.

Use .obsp[obsp] as adjacency. You can’t specify both obsp and neighbors_key at the same time.

copy bool (default: False)

Deprecated since version 1.13.0: Copy adata before calling this function instead.

Return a copy instead of writing to adata.

key_added_ext str | None (default: None)

Replaces layout in the default key, i.e. writes .obsm['X_draw_graph_{key_added_ext}'].

**kwds

Parameters of chosen igraph layout. See e.g. layout_fruchterman_reingold() [Fruchterman and Reingold, 1991]. One of the most important ones is maxiter.

Return type:

AnnData | ndarray | None

Returns:

Returns the embedding if out=True, else None. By default sets the following fields (see out for others):

adata.obsm['X_draw_graph_{layout}']numpy.ndarray (dtype float)

Coordinates of graph layout. E.g. for layout='fa' (the default), the field is called 'X_draw_graph_fa'.

adata.uns['draw_graph']: dict

draw_graph parameters.