Embedding: Embedding an abstract complex into space¶
- class simplicial.Embedding(c, dim=2)¶
The abstract embedding of a simplicial complex into a space. An embedding associates a position with each 0-simplex in the complex, allowing spatial calculations to be performed.
Embeddings serve two distinct purposes. Firstly, they admit spatial calculations as well as purely topological ones, which broadens the application areas to which we can apply simplicial ideas. Secondly, embeddings form the basis for visualisation, as they allow points (0-simplices) in a complex to be associated with points in an n-dimensional embedding space. This can result in more meaingful diagrams.
An embedding can be specified in two distinct ways. Positions can be supplied explicitly for simplices by name. Alternatively, sub-clases can provide positioning functions that map simplices to positions using arbitrary code. The former is useful for complexes with irregular embeddings, while the latter is better-suited to regular embeddings. Explicit positions override computed positions, which allows small distortions to be applied easily to otherwise regular embeddings.
It is also possible to override the distance metric to construct different ways of metricating a space. The default is n-dimensional Euclidean.
Note that in most cases an embedding is based on simplex names, and so care needs to be taken when relabeling simplices in the underlying complex.
- Parameters
c (
SimplicialComplex) – the complexdim (
int) – the dimension of the embedding space (defaults to 2)
Important
Embeddings are also used to support simplicial’s
drawing routines.
Basic properties of the embedding space¶
The embedding space can have any number of dimensions, defaulting to two. (At present simplicial only supports Euclidian embedding spaces.)
- Embedding.dimension()¶
Return the dimension of the embedding space.
- Return type
int- Returns
the dimension of the embedding space
- Embedding.origin()¶
Return the position of the origin of the embedding space.
- Return type
List[float]- Returns
the origin as a list of zero co-ordinates
- Embedding.complex()¶
Return the underlying simplicial complex.
- Return type
- Returns
the complex
The locations give rise to a notion of distance between positions.
- Embedding.distance(p, q)¶
Compute the distance between two points. This implementation returns the normal n-dimensional Euclidean distance.
- Parameters
p (
List[float]) – one pointq (
List[float]) – the other point
- Return type
float- Returns
the distance between them
Positioning simplices¶
An embedding works by specifying the positions of the 0-simplices of a complex. Since all higher simplices have a basis constructed of 0-simplices, these positions then induce positions for all the higher-order simplices.
There are two ways to specify an embedding. The first is to provide
explicit co-ordinates for every 0-simplex in a complex. This is very
general but misses some frequent commonalities, and so the second way
is to provide a sub-class of Embedding that overrides the
Embedding.computePositionOf() method. The two methods play well
together: one can provide a sub-class to capture the regularities, and
then perturb the complex by moving individual points if
required. (Client code should only use Embedding.positionOf() to
access simplex positions, and not access to computation method
directly. This ensures that explicit positions are returned correctly
and cached.)
- Embedding.positionSimplex(s, pos)¶
Define an explicit position for a simplex.
- Parameters
s (
Any) – the simplexpos (
List[float]) – the position
- Embedding.computePositionOf(s)¶
Compute the position of the given 0-simplex under this embedding. The position returned should have the same dimensions as the embedding space. This method should be overridden by sub-classes: the default returns the origin for all 0-simplices.
- Parameters
s (
Any) – the simplex- Return type
List[float]- Returns
the position of the simplex
- Embedding.positionOf(s)¶
Return the position of a simplex in the complex when mapped through this embedding. Locations are only available for 0-simplices.
- Parameters
s (
Any) – the simplex- Return type
List[float]- Returns
the position of the simplex
- Embedding.positionsOf(ss=None)¶
Return a dict of positions for a given set of 0-simplices in the complex. The default is to return the positions of all 0-simplices.
- Parameters
ss (
Optional[Set[Any]]) – the simplices (defaults to all 0-simplices)- Return type
Dict[Any,List[float]]- Returns
a dict of positions
- Embedding.clearPositions()¶
Clear the cache of simplex positions, forcing them all to be re-computed and/or re-specified. Use this if the underlying complex is changed.
Dict-like interface¶
Embedding also exports a dict-like interface.
- Embedding.__len__()¶
The length of the embedding is the number of 0-simplices in the underlying simplicial complex, i.e., the number of simplices we can return positions for.
- Return type
int- Returns
the size of the embedding
- Embedding.__getitem__(s)¶
Dict-like interface to return the position of a simplex in the complex when mapped through this embedding. Equivalent to
positionOf().- Parameters
s (
Any) – the simplex- Return type
List[float]- Returns
the position of the simplex
- Embedding.__setitem__(s, pos)¶
Dict-like interface to define an explicit position for a simplex. Equivalent to
positionSimplex().- Parameters
s (
Any) – the simplexpos (
List[float]) – the position
- Embedding.__contains__(s)¶
Test if the embedding will embed the given simplex. Checks against the underlying simplicial complex.
- Parameters
s (
Any) – the simplex- Return type
bool- Returns
True if the embedding comtains the simplex
Spatial constructions¶
Embeddings apply a geometry to a topological structure. It can be useful to go the other way: to take some geometric or spatial information and create a topological structure from it, where the topological structure encodes useful information. Typically this depends on a notion of distance between the located 0-simplices. The distance metric can then provide a way of constructing higher-dimensional simplices.
- Embedding.vietorisRipsComplex(eps)¶
Construct the Vietoris-Rips complex at scale eps corresponding to the given embedding. The resulting complex has the same 0-simplices as the embedding, with a simplex constructed between every collection of simplices that are mutually a distance eps or less apart.
- Parameters
eps (
float) – the scale parameter- Return type
- Returns
the Vietoris-Rips complex at the given scale