Networks

Overview

StructuralGT.networks.Network

Generic class to represent networked image data.

Details

class StructuralGT.networks.Network(directory, binarized_dir='Binarized', depth=None, prefix=None, dim=2)

Bases: object

Generic class to represent networked image data.

Args:

directory (str):

The (absolute or relative) pathname for the image(s) to be analysed. Where 2D analysis is concerned, the directory should contain a single image.

binarized_dir (str):

The pathname relative to directory for storing the binarized stack of images and all subsequent results.

depth (tuple, optional):

The file range from which files should be extracted from the directory. This is primarily used to analyse a subset of a large directory. Cropping can be carried out after, if this argument is not specified.

prefix (str, optional):

The characters preceding numbers in the filename of the image. Default is “slice”.

dim (int, optional):

The dimensionality of the network, either 2 or 3. Default is 2.

binarize(options='img_options.json')

Binarizes stack of experimental images using a set of image processing parameters.

Args:

options (dict, optional):

A dictionary of option-value pairs for image processing. All options must be specified. When this arguement is not specified, the network’s parent directory will be searched for a file called img_options.json, containing the options.

set_img_bin(crop)

Set the img_bin and img_bin_3d attributes.

This is called internally by subclasses of Network.

Args:

crop (list):

The x, y and (optionally) z coordinates of the cuboid/ rectangle which encloses the Network region of interest.

set_graph(sub=True, weight_type=None, write='network.gsd', R_j=0, rho_dim=1)

Sets Graph object as an attribute by reading the skeleton file written by img_to_skel().

Args:

sub (optional, bool):

Whether to only assign the largest connected component as the igraph.Graph object.

weight_type (optional, List[str]):

List of weights to include for edges. Options include Length, Width, Area, InverseLength, FixedWidthConductance, VariableWidthConductance, Resistance, PerpBisector.

write (optional, str):

Filename that graph should be written to.

R_j (optional, float):

Junction resistance used for electrical weight types.

rho_dim (optional, float):

Scaling parameter mapping pixel length to resistance used for electrical weight types. If weight_type is VariableWidthConductance, this should have units \(Ohm\) pixels. If weight_type is FixedWidthConductance, this should be resistivity/cross_sectional_area.

img_to_skel(name='skel.gsd', crop=None, skeleton=True, rotate=None, debubble=None, box=False, merge_nodes=None, prune=None, remove_objects=None)

Writes calculates and writes the skeleton to a .gsd file.

Note: if the rotation argument is given, this writes the union of all of the graph which can be obtained from cropping after rotation about the origin. The rotated skeleton can be written after the graph attribute has been set.

Args:

name (str):

File name to write.

crop (list):

The x, y and (optionally) z coordinates of the cuboid/ rectangle which encloses the Network region of interest.

skeleton (bool):

Whether to write the skeleton or the unskeletonized binarization of the image(s).

rotate (float):

The amount to rotate the skeleton by after the graph attribute has been set.

debubble (list[numpy.ndarray]):

The footprints to use for a debubbling protocol.

box (bool):

Whether to plot the boundaries of the cropped Network.

merge_nodes (int):

The radius of the disk used in the node merging protocol, taken from [VMHK21].

prune (int):

The number of times to apply the pruning algorithm taken from [VMHK21].

remove_objects (int):

The size of objects to remove from the skeleton, using the algorithm in [VMHK21].

node_labelling(attributes, labels, filename='labelled.gsd', edge_weight=None, mode='w', csv_write=True)

Method saves a new .gsd which labels the graph attribute with the given node attribute values. Method saves the graph attribute in the .gsd file in the form of a sparse adjacency matrix (therefore edge/node attributes are not saved).

Args:

attributes (list[numpy.ndarray]):

A list of arrays of attribute values, with each array listing attribute values in in ascending order of node id.

label (list[str]):

A list of the labels to give the attribute in the file.

filename (str):

The file name to write.

edge_weight (optional, numpy.ndarray):

Any edge weights to store in the adjacency matrix.

mode (optional, str):

The writing mode. See the gsd documentation for details.

node_plot(parameter=None, ax=None, depth=0, plot_img=True)

Superimpose the skeleton, image, and nodal graph theory parameters. If no parameter provided, simply imposes skeleton and image.

Args:

parameter (numpy.ndarray, optional):

The value of node parameters

ax (matplotlib.axes.Axes, optional):

Axis to plot on. If None, make a new figure and axis. (Default value = None)

depth (int, optional):

If the Network is 3D, which slice to plot.

plot_img (bool, optional):

Whether to plot the image or not.

Returns:

(matplotlib.axes.Axes): Axis with the plot.

edge_plot(parameter=None, ax=None, depth=0, edge_cmap='plasma', plot_img=True, **kwargs)

Superimpose the skeleton, image, and nodal graph theory parameters. If no parameter provided, simply imposes skeleton and image.

Args:

parameter (numpy.ndarray, optional):

The value of node parameters

ax (matplotlib.axes.Axes, optional):

Axis to plot on. If None, make a new figure and axis. (Default value = None)

depth (int, optional):

If the Network is 3D, which slice to plot.

edge_cmap (Colormap or str, optional):

The colormap used for plotting edges.

plot_img (bool, optional):

Whether to plot the image or not.

kwargs (optional):

Keyword arguements to pass to ax.scatter.

Returns:

(matplotlib.axes.Axes): Axis with the plot.

graph_plot(ax=None, depth=0)

Superimpose the graph and original image.

Args:

ax (matplotlib.axes.Axes, optional):

Axis to plot on. If None, make a new figure and axis. (Default value = None)

depth (int, optional): If the network is 3D, which slice to plot.

Returns:

(matplotlib.axes.Axes): Axis with the plot.

recon(axis, surface, depth)

Method displays 2D slice of binary image and annotates with attributes from 3D graph subslice

property img_bin

np.ndarray: The binary image from which the graph was extracted

property graph

igraph.Graph: The Graph object extracted from the skeleton

property image

np.ndarray: The original image used to obtain the graph.

property skeleton

np.ndarray: The original skeleton.

classmethod from_gsd(filename, frame=0, depth=None, dim=2, prefix='slice')

Alternative constructor for returning a Network object that was previously stored in a .gsd and .json file. Assumes file is stored in the same directory as StructuralGT wrote it to. I.e. assumed name given as …/dir/Binarized/name.gsd.

StructuralGT.networks.Graph(filename, frame=0)

Function which returns an igraph.Graph object from a gsd, with node and edge position attributes. Useful when a Network object is not required. Unlike Network.from_gsd, it makes no assumptions about the path of the gsd file.

Args:

filename (str):

The file name to read.

frame (int, optional):

The frame to load from the gsd.

Returns:

(igraph.Graph): igraph Graph object.

class StructuralGT.networks.GeometricGraph(filename, frame=0)

Bases: object

Args:

filename (str):

The file name to read.

frame (int, optional):

The frame to load from the gsd.

Returns:

(igraph.Graph): igraph Graph object.

class StructuralGT.networks.ParticleNetwork(trajectory, cutoff, partition=0, periodic=False)

Bases: Sequence

Class for extracting sliceable list of graphs from gsd files.

Args:

trajectory (str):

The filename of the trajectory.

count(value) → integer -- return number of occurrences of value

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

class StructuralGT.networks.PointNetwork(positions, edge_builder, periodic=False)

Bases: object

Class for creating graphs from point cloud data.

Args:

positions (numpy.ndarray):

The coordinates of the points in the point cloud.

edge_builder (dict or numpy.ndarray):

The edge_builder distance for creating edges between points.

periodic (bool):

Whether to use periodic boundary conditions. Default is False.

set_graph(filename='skel.gsd', weights=None)

Method saves a new .gsd with the graph structure.

Args:

filename (str):

The filename to save the .gsd file to.

node_labelling(attributes, labels, filename='labelled.gsd', csv_write=True)

Method saves a new .gsd which labels the graph attribute with the given node attribute values.

Args:

attributes (list[numpy.ndarray]):

A list of arrays of attribute values, with each array listing attribute values in in ascending order of node id.

label (list[str]):

A list of the labels to give the attribute in the file.

filename (str):

The file name to write.

edge_labelling(attributes, labels, filename='edge_labelled.gsd')

Method saves a new .gsd which labels the graph attribute with the given edge attribute values.

Args:

attributes (list[numpy.ndarray]):

A list of arrays of attribute values, with each array listing attribute values in in ascending order of edge id.

label (list[str]):

A list of the labels to give the attribute in the file.

filename (str):

The file name to write.

classmethod from_gsd(filename, edge_builder, frame=0)

Alternative constructor for returning a PointNetwork object that is stored in a .gsd file.

Args:

filename (str):

The filename to read the .gsd file from.

frame (int, optional):

The frame to load from the gsd.