Relabel

Watch the video tutorial on this subject!

Regular Expressions

This feature allows you to automatically relabel items in the neural network and body of an organism using regular expression strings. Regular expressions have been widely popular in languages such as PERL and AWK and have been utilized for pattern matching, text manipulation and text searching. These languages are specifically is known for their advanced pattern matching features. Regular expressions in AnimatLab are based on that of Perl and are compatible with Perl 5 regular expressions.

Regular Expression Elements

Some of the commonly used regular expression elements are:

^	Matches start of input
$	Matches end of input
.	Matches any character except new line
\|	OR
*	Match the preceding expression 0 or more number of times
+	Match the preceding expression 1 or more number of times
?	Match the preceding expression 0 or 1 number of times
()	Logical group / sub-expression (capture as auto number group)
(?<exp>)	Named capture group
(?=exp)	Match any position preceding a suffix exp
(?<=exp)	Match any position following a prefix exp
(?!exp)	Match any position after which exp is not found
(?<!--exp)	Match any position before which exp is not found
[…]	List of characters to match
[^expression]	Not containing any of the specified character
{n} or {n. m}	Quantifier (Match exact number or range of instances)
(?(exp (yes\|no))	If expression (exp) is true match yes part else no part
\	Escape character (to match any of the special characters)
\w	Match any word character
\W	Match any non-word character
\s	Match any white space character
\S	Match any non-white space character
\d	Match any numeric digit
\D	Match any numeric digit
\b	Match a backspace if in character matching mode ([]). Otherwise match the position at beginning or end of a word
\t	Match tab
\r	Match carriage return
\n	Match line feed

The following are matching substitutions:

num	Substitute last substring matched by group number num
${name}	Substitute last substring matched by group name
$&	Substitute a copy of entire text itself
$`	Substitute all the text of the input string before match
$’	Substitute all the text of the input string after match
$+	Substitute last matched group
$_	Substitute input string
$$	Substitute literal $

Regular expressions could also be used to find repeating patterns by making use of backreferencing, using this you can name a pattern found and then use that reference elsewhere in expression. For more advanced subject like this please consult websites that go into detail on using regular expressions. A useful site is microsofts description of how it implements regular expressions found here. This site gives a tutorial on using regular expressions.

Relabeling Items

You can relabel items in the neural network by clicking on the Relabel button in the toolbar, , or by selecting it in the pop-up menu. It displays the relabel dialog. Here you can type in a matching string and replacement string. When you are ready you hit the relabel button. This feature has the potential to make a large number of changes. In fact, its possible to accidentally change the name of every object in the body. So before the changes are actually made the confirm dialog is shown. This lists all matching objects and shows their current name, and the new name they will have when this process finishes.

You can choose to apply these changes to this diagram only, this subsystem, or to all diagrams in the editor. If you choose to apply it to the subsystem it will match the expression to all items in the current diagram and all of its children. This way if you have a subsystem for a leg that has child systems you can change the label throughout the entire chain of subsystems without changing nodes in the other systems for other legs.

Within the body editor the 3 radio buttons are not shown, but you still have the ability to apply the relabel feature to different levels. If you select relabel while the organism node is selected it will apply it to all items in the body, but if select another node in the tree it will apply the changes to that body and all of its children.

Figure 1. Relabel Dialog.

Figure 2. Confirm dialog that shows the changes that will be made if the relabel is committed.

Relabel Examples

I will go over two simple examples to demonstrate how to use this features. To actually see the examples in action please watch the video tutorial.

The first example assumes that you are trying to build a six limbed animal and you are using a naming convention where you start the labels with a two letter prefix for the leg followed by and underscore and then the items name. For example, LU_Backwards would be the backwards neuron for the left upper leg. If we copy and past the subsystem for the left upper leg we can change the copy to work for the other legs. If we do this for the right upper leg then we will need to change the labels on all of the items within that subsystem. Set the match expression to be "LU_*". This says to find all names that start with "LU_" and then have any text following. It will then replace those matching strings with "RU_" followed by the other text in the name. This provides an easy way to change labels using a simple naming convention.

The next example is a little more complicated. Say you want to find all names that start with "LU_", have a number, and then are followed by an underscore and any text. Here is an example that matches this template: "LU_23_My Test". Here are some that do not match it: "LU_C_Test, LU_Test, MyTest". We can perform this more complicated matching prodedure using backreferencing. This allows you to have regular expressions that pick out substrings and attach a name to the substrings. You can then use the named strings in your replace expression.

This time use the following match expression: "(?<Prefix>LU_)(?<Count>\d)(?<Name>_*)". These symbols (?<Name>Match String) specifies that any substring matching LU_ should be attached to the label prefix. Similarly, the count name will be attached to a following number. Use this for the replace expression "RU_${Count}${Name}". The ${Count} symbols tell it to use the substring it found that matched the one we called count in the matching expression.

Backreferencing and regular expression give you a tremendously flexible tool for performing bulk changing of names.