Batch Rename

This tool has been deprecated and will be retired in a future version of the software. It has been moved to the Legacy Tools () folder of the Toolbox, and its name has "(legacy)" appended to it. The functionality of this tool has been replaced by two new tools, Rename Elements, for renaming data elements (Rename Elements), and Rename Sequences in Lists for renaming sequences within sequence lists (Rename Sequences in Lists). We recommend using these new tools instead of Batch Rename (legacy).

To run the Batch Rename (legacy) tool:

Toolbox | Legacy Tools () | Batch Rename (legacy) ()

This will open the dialog shown in figure 36.1 where you can select the input data.

Image batch_rename_step1
Figure 36.1: Selecting the data you want to rename.

Click Next to go to the next dialog (see figure 36.2).

Here, one can choose to include or exclude only some of the data previously selected to work on. For small numbers of data elements, this would not usually be necessary. However, if many data objects were selected at the previous step (to save time when choosing many data elements) you could use the include or exclude functionality at this point so that only certain data elements will be acted upon.

Image batch_rename_step2
Figure 36.2: Select how to filter the input data.

The Include and Exclude filters take the text entered into the respective fields and search for matches in the names of the data elements selected in the first wizard step. Thus, you could enter the full names of particular data elements, or just partial names. Any elements where a match is found to the term or terms in the Include field will have the batch renaming applied to them. Any elements where a match is found to the term or terms in the Exclude field will not have the batch renaming applied to them.

For both filters, if you wish to filter on more than one term at the time, the individual terms must be separated with a comma - and without using a space after the comma. An example is shown in figure 36.3.

Image batch_rename_step2_exclude
Figure 36.3: Items remaining after filtering away items with a Q or an O in their name.

In the "Select Target type" step, you can specify at which level you wish to perform the renaming. For a single sequence this is straightforward because it has just one name, and you would use the Rename elements option. But if you have a sequence list - as in the example shown in figure 36.4 - you could choose either to rename the list (using Rename elements) or the sequences in the list (using Rename sequences in sequence lists). The same goes for alignments (using Rename sequences in alignments) and read mappings (using Rename reads in mappings). For read mappings, there is also an option to Rename reference sequence in mappings.

Image batch_rename_step3
Figure 36.4: In this example, as we only have one category represented, the other target type options are disabled.

Click Next to open the last dialog (see figure 36.5). For each text field, you can press Shift+F1 (Shift + Fn + F1 on Mac) to get a drop-down list of advanced placeholder options.

Image batch_rename_step4
Figure 36.5: Rename options. At this step you can choose whether you wish to add text to the existing name, replace some of the name, or replace the entire name.

At this step you can select between three different renaming options.

Add text to name This option keeps the original name and adds text to the beginning or the end of it. Text can be added directly. Alternatively, placeholders for certain types of information can be entered. Press Shift + F1 (Shift + Fn + F1 on Mac) to see a list of these (figure 36.5). An example is #BR-E#, short for "Batch Rename - Enumeration". With this option, consecutive numbers are added according to the order the data were selected in the first dialog under "Select Elements".
Replace part of name Replace a part of each name, as specified by text to be interpreted literally, or as a Java regular expression when the "Intepret 'Replace and 'With' as Java Regular Expressions" box is checked (figure 36.6). Text, placeholders, or regular expressions to be substituted in the names is entered in the "With" field. Leave the "With" field empty if the specified parts of the name should be removed without replacement.
For more information on regular expressions, see: http://docs.oracle.com/javase/tutorial/essential/regex/.

Figure 36.6: Common regular expression terms for renaming part of a name are presented if you click in the Replace field and press Shift + F1 (Shift + Fn + F1 on Mac).
By clicking in either the Replace field and pressing the Shift + F1 keys (Shift + Fn + F1 on Mac), a list of common regular expressions is presented. Other standard regular expressions can also be used. The same key combination when the cursor is in the With field pops up a list of placeholders that can be used.
Note:The "Intepret 'Replace and 'With' as Java Regular Expressions" must be checked for terms to be interpreted as regular expressions. When not checked, text entered is interpreted literally.
Example: If you enter "Replace" "Regular Expression: Range ([A-Z]) "With" "Enumeration (#BR-E#)", titles containing any (capital) letters will be renamed to consecutive numbers. See figure 36.7 for an example that expands on this.

Figure 36.7: [A-Z][a-z]2 indicates that a large letter followed by two small letters should be replaced. This finds the text Fwd in each element name, and that is replaced with today's date, expressed using a placeholder. The With field also indicatesa space and a "_"character should be added. The number at the end of each of the original names is retained.
A few more examples:
- Rename using the first 4 non-whitespace characters from names that start with 2 characters, then have a space, then have multiple characters following, such as 1N R1\_0001.
  - Check the box beside "Interpret 'Replace' and 'With' as Java regular expressions".
  - Enter ([\w]{2})\s([\w]{2}).* into the "Replaces" field.
  - Enter $1$2 into the "with" field.
- Keep only the last 4 characters of the name.
  - Check the box beside "Interpret 'Replace' and 'With' as Java regular expressions".
  - Enter (.*)(.{4}$) into the "Replaces" field.
  - Enter $2 into the "with" field.
- Replace a set pattern of text with the name of the parent folder. Here, we start with the name p140101034_1R_AMR and replace the first letter and 9 numbers with the parent folder name.
  - Check the box beside "Interpret 'Replace' and 'With' as Java regular expressions".
  - Enter ([a-z]\d{9})(.*) into the "Replaces" field.
  - Enter #BR-F#$2 into the "with" field.
- Rename using just the text between the first and second underscores in 1234_sample-code_5678.
  - Check the box beside "Interpret 'Replace' and 'with' as Java regular expressions".
  - Enter (^[^_]+)_([^_]+)_(.*) into the "Replaces" field.
  - Enter $2 into the "with" field.
Replace full name Allows replacement of the entire name with the name that is either typed directly into the text field, or with options that can be selected when pressing Shift + F1 (Shift + Fn + F1 on Mac). Figure 36.8 shows an example where a combination of "Shift +F1" (Shift + Fn + F1 on Mac) options (#BR-D# and#BR-E#) are used together with user-defined text (RNA-Seq).

Image batch_rename_full_name
Figure 36.8: The entire name is removed from the primer names and is replaced with "Today's date" (#BR-D#), the userdefined text: RNA-Seq, and the addition of consecutive numbers (#BR-E#). In this case we have inserted a space between the date, the user-defined text and the added number. If commas were inserted instead, the commas would be part of the new name as everything that is typed into the text field will be used in the new name when renaming the entire name.

Click Finish to start renaming. Please note that the rename cannot be undone and that it does not show up in the History ().

Browse the manual

Batch Rename