Rag

• Rag

  • __init__

  • supported_features

  • compute_features

  • edge_decisions_from_groundtruth

  • naive_segmentation_from_edge_decisions

  • serialize_hdf5

  • deserialize_hdf5

  • dense_edge_tables

class ilastikrag.rag.Rag(label_img, flat_superpixels=False)

Region Adjacency Graph

Initialized with an ND label image of superpixels, and stores the edges between superpixels.

Attribute	Description
label_img	The label volume you passed in.
sp_ids	1D ndarray of superpixel ID values, sorted.
max_sp	The maximum superpixel ID in the label volume
num_sp	The number of superpixels in label_img. Not necessarily the same as max_sp.
num_edges	The number of edges in the label volume.
edge_ids	ndarray, shape=(N,2) List of adjacent superpixel IDs, sorted. (No duplicates). Guarantee: For all edge_ids (sp1,sp2): sp1 < sp2.
unique_edge_tables	dict of pandas.DataFrame objects Columns: [sp1, sp2, edge_label], where edge_label uniquely identifies each edge (sp1, sp2) within that table. See unique_edge_tables for details.
dense_edge_tables	OrderedDict of pandas.DataFrame objects (one per isotropic axis). Each DataFrame stores the id and location of all pixel edge pairs in the volume along a particular axis. See dense_edge_tables for details.
flat_edge_label_img	ndarray, same shape as label_img except for the z-axis (1 px smaller) If flat_superpixels=True, this is a label volume for edges along the z-axis, labeled according to the edge_label column from unique_edge_tables['z'].

Limitations:

• This representation does not check for edge contiguity, so if two superpixels are connected via multiple ‘faces’, those faces will both be lumped into one ‘edge’.

• No support for parallelization yet.

__init__(label_img, flat_superpixels=False)

Parameters:

• label_img – VigraArray
  Label values do not need to be consecutive, but excessively high label values will require extra RAM when computing features, due to zeros stored within RegionFeatureAccumulators.

• flat_superpixels – bool
  Set to True if label_img is a 3D volume whose superpixels are flat in the xy direction.

supported_features(accumulator_set='default')

Return the set of available feature names to be used with this Rag and the given accumulator_set.

Parameters:

accumulator_set – A list of acumulators to consider in addition to the built-in accumulators. If accumulator_set="default", then only the built-in accumulators are considered.

Returns:

The list acceptable feature names.

Return type:

*list* of str

compute_features(value_img, feature_names, edge_group=None, accumulator_set='default')

The primary API function for computing features.
Returns a pandas DataFrame with columns ['sp1', 'sp2', ...output feature names...]

Parameters:

• value_img – VigraArray, same shape as self.label_img.
  Pixel values are converted to float32 internally.
  If your features are computed over the labels only,
  (not pixel values), you may pass value_img=None
  

• feature_names –

  list of str

  Feature names must have the following structure:

  <accumulator_id>_<type>_<feature>.
  

  Example feature names:

  • standard_edge_count

  • standard_edge_minimum

  • standard_edge_variance

  • standard_edge_quantiles_25

  • standard_sp_count

  • standard_sp_mean

  The feature names are then passed to the appropriate EdgeAccumulator or SpAccumulator. See accumulator docs for details on supported feature names and their meanings.

  Features of type edge are computed only on the edge-adjacent pixels themselves. Features of type sp are computed over all values in the superpixels adjacent to an edge, and then converted into an edge feature, typically via sum or difference between the two superpixels.

• edge_group –

  str or list-of-str
  If Rag.flat_superpixels=True, valid choices are 'z' or 'yx', or ['z', 'yx'], in which case an OrderedDict is returned with both results.

  For isotropic rags, there is only one valid choice, and it is selected by default: 'zyx' (or 'yx' if Rag is 2D).

• accumulator_set – A list of acumulators to use in addition to the built-in accumulators. If accumulator_set="default", then only the built-in accumulators can be used.

Returns:

All unique superpixel edges in the volume, with computed features stored in the columns.

Return type:

*pandas.DataFrame*

Example

>>> rag = Rag(superpixels)
>>> feature_df = rag.compute_features(grayscale_img, ['standard_edge_mean', 'standard_sp_count'])
>>> print list(feature_df.columns)
['sp1', 'sp2', 'standard_edge_mean', 'standard_sp_count_sum', 'standard_sp_count_difference']

sp1	sp2	standard_edge_mean	standard_sp_count_sum	standard_sp_count_difference
1	2	123.45	1000	42
1	3	234.56	876	83
…	…	…	…	…

edge_decisions_from_groundtruth(groundtruth_vol, asdict=False)

Given a reference segmentation, return a boolean array of “decisions” indicating whether each edge in this RAG should be ON or OFF for best consistency with the groundtruth.

The result is returned in the same order as self.edge_ids. An OFF edge means that the two superpixels are merged in the reference volume.

If asdict=True, return the result as a dict of {(sp1, sp2) : bool}

naive_segmentation_from_edge_decisions(edge_decisions, out=None)

Given a list of ON/OFF labels for the Rag edges, compute a new label volume in which all supervoxels with at least one inactive edge between them are merged together.

Requires networkx.

Parameters:

• edge_decisions – 1D bool array in the same order as self.edge_ids
1 means “active”, i.e. the SP are separated across that edge, at least.
  0 means “inactive”, i.e. the SP will be joined in the final result.
  

• out – VigraArray (Optional).
  Same shape as self.label_img, but may have different dtype.
  

Return type:

*VigraArray*

serialize_hdf5(h5py_group, store_labels=False, compression='lzf', compression_opts=None)

Serialize the Rag to the given hdf5 group.

Parameters:

• h5py_group – h5py.Group
  Where to store the data. Should not hold any other data.

• store_labels – If True, the labels will be stored as a (compressed) h5py Dataset.
  If False, the labels are not stored, but you are responsible
  for loading them separately when calling dataframe_to_hdf5(),
  unless you don’t plan to use superpixel features.

• compression – Passed directly to h5py.Group.create_dataset.

• compression_opts – Passed directly to h5py.Group.create_dataset.

classmethod deserialize_hdf5(h5py_group, label_img=None)

Deserialize the Rag from the given h5py.Group, which was written via Rag.serialize_to_hdf5().

Parameters:

label_img – If not None, don’t load labels from hdf5, use this volume instead. Useful for when serialize_hdf5() was called with store_labels=False.

dense_edge_tables

Read-only property.
A list of pandas.DataFrame objects (one per image axis).
Each DataFrame stores the location and superpixel ids of all pixelwise
edge pairs in the volume along a particular axis.

Example:

sp1	sp2	forwardness	edge_label	z	y	x
1	2	True	10	0	10	13
1	2	False	10	0	10	14
1	2	False	10	0	10	15
1	3	True	11	1	20	42
1	3	True	11	1	20	43
1	3	False	11	1	20	44
…	…	…	…	…	…	…

Column definitions:

Column	Description
sp1	Superpixel ID
sp2	Superpixel ID. Guarantee: (sp1 < sp2)
forwardness	True if sp1 was on the “left” (or “upper”, etc.) side of the edge.
edge_label	A uint32 that uniquely identifies this (sp1,sp2) pair, regardless of axis.
z	Z-coordinate of this pixel edge
y	Y-coordinate of this pixel edge
x	X-coordinate of this pixel edge