Region tagging

Module: tutorials.02_EP_tissue.04_tagging.run

Section author: Edward Vigmond <edward.vigmond@u-bordeaux.fr>

In CARPentry regions are used to manage the assignment of heterogeneous tissue properties. This tutorial explains the different approches of how regions can be defined.

Regions

Regions are a general concept in CARPentry for volumes which share common properties, be they ionic, mechanical or conductivity. For a general introduction of this concept see the region section of the manual. In the mesh files, elements may be given a region tag as an optional field in the .elem file.

Note

If no region tag is specified, the element is assigned a region tag of 0.

A region tag is a simply an integer associated with an element. CARPentry regions are then conglomerations of element region tags. The following is an example of how to assign some region tags to IMP and conductivity regions:

imp_region[1].num_IDS = 2
imp_region[1].ID[0] = 1000 
imp_region[1].ID[1] = 1100

gregion[3].num_IDS = 5
gregion[3].ID = 100 200 201 1000 2000 

Two slightly different syntaxes are shown for specifying the region tags.

Note

If a region tag is not explicitly included in any region, it will be assigned to region 0.

Dynamic Retagging

Each element in a mesh is designated as being in a region, and properties, be they electrical or mechanical, are assigned based on region. It may be desired to change properties in a small volume which is not defined in the original mesh. To avoid touching the mesh files, dynamic tagging was introduced.

Essentially, a geometrical volume is defined, and all elements wthin the volume are given a new tag. Overlaps are governed by a simple rule: the highest region tag wins. This also implies that your reassigned tags have to be higher than the original model tags. The case where some but not all of an element’s nodes are contained with the tagging volume must be handled. By default, elements with at least one node in the tagging volume are included, but ensuring that only elements with all nodes contained can be enabled by setting an option below.(no_split_elem)

Tag volumes can also be created by simply specifying a list of elements within the volume.

Region Definitions

The number of new tag regions is specified by numtagreg. For each region defined by tagreg[*], the table below lists the available fields to set. Bolded fields need to be specified and depending on the value of type, different fields define the geometrical volume. Note that the units are micrometers. See the figure below:

Field Meaning
tag numerical value of tag region
name string to identify retagged region
type how to define region (1=sphere,2=block,3=cylinder,4=elemfile)
no_elem_split all nodes of an element must be contained
p0 first point to define volume. type=1|2|3
p1 second point to define volume. type=2|3
radius radius for spherical/cylindrical volumes. type=1|3
elemfile file with elements contained in tag region. type=4 The file needs the extension .regele with the format being the number of elements followed by one element number per line.

The tagging volumes are defined according to the following diagram:

../../_images/retag-vols.png

Fig. 74 Geometry definitions for dynamic retagging volumes sphere, block and cylinder.

Mesher Tagging

When using the mesher program, tag volumes can be assigned to the blocks of tissue but the rules are slightly different.

Note

With mesher, bounds are defined in units of cm, not micrometers and the cylinder definition is different.

For each tag volume defined by regdef[*], the table below lists the available fields to set. Bolded fields need to be specified and depending on the value of type, different fields define the geometrical volume.

Field Meaning
tag numerical value of the tag
type how to define tag volume (0=block,1=sphere,2=cylinder)
p0 first point to define volume. type=0|1|2
p1 UR point for block (type=0), or axis for cylinder which will be normalized (type=2)
rad radius for spherical/cylindrical volumes. type=1|2
cyllen cylinder length for cylindrical volumes. type=2
bath set true for a bath region
../../_images/regions-mesher-cyl.png

Fig. 75 Geometry definition for mesher cylinder. Spheres and blocks are defined as in dynamic retagging above.

If an element was originally created as bath, it cannot be turned into myocardium but myocardium can be turned into bath. To deal with overlapping regions, the rules are also different from dynamic tagging. For mesher, an element belongs to the first region which contains it. Thus, the order of region definitions is important. An option is also available -first_reg, which if set false, scans the region definitions and assigns the last region which contains an element.

Tutorial

The following options are the pertinent ones for running the tutorial:

run.py -h
    --mesher [{sphere,block,steps} [{sphere,block,steps} ...]]
                    regions implemented in mesher
    --dynamic [{cylinder,sphere,block} [{cylinder,sphere,block} ...]]
                    regions implemented dynamically
    --add-bath            mesher regions are bath

Multiple regions can be created in meshser or dynamically afterwards. Start with a single region implemented in mesher:

run.py --mesher sphere

To see the regions better, click Image/Randomly color/surfaces from the menu ar at the top. The colors are random, so if you do not like them, randomly color again (and again …). You should see 3 regions: the bath, the original block of tissue, and the sherical region; To see the points in the region,

  1. turn off clipping (open the clipping window under Data/Clipping)
  2. In the Region section in the control window, check only the region 10
  3. Check the Vertices and visible buttons
  4. To control the size of the points, click on props beside the Vertices button.
  5. Reduce the opacity of the surfaces (set it in Fill color of the Surfaces tab)

It should now resemble the figure below.

../../_images/regions_sphpts.png

Try adding another sphere, this time dynamically added afterwards at a different location:

run.py --mesher sphere --dynamic sphere

Experiment with adding different combinations of regions. The order of multiple regions specified with the --mesher and --dynamic options matters. With this script, the first contained region is used for dynamic retagging. To see the points contained in the regions, display vertices as above, and click Image/Randomly color/surfaces to colour them differently for each tag region.

For a more detailed introduction to the region concept as implemented in CARPentry see the Region Tagging Section of the manual.