Editing Object Properties

3.5.10

After you have finished entering various objects into a Project, you may find it necessary to edit properties and correct mistakes. There are several commands that let you alter the Project data after they have already been entered into the system.

3.5.10.1

Updating an Object

One way to edit an object is to use the “update” command (see section 3.4.16 for the usage statement). In the example Project, we find that the region 4 Read Data Set is actually empty. Since the “load” command used to import Read Data Sets defaults the “active” flag to true, we need to change that flag to false, for this Read Data Set:

update readData EGFR_reads04 -active false

The update command is of the form “update <entity type> <name of entity> [other options]” where the “other options” are used to set the values for properties appropriate for the entity type. The only object property that cannot be updated via the update command is the object’s name. To change the name of an object, use the “rename” command (section 3.5.10.2, below).

When updating an Amplicon or a Variant, you can use an “ofRef” parameter to fully specify the entity of interest in cases where the multiple entities may share the same name (but are uniquely named in the context of their particular Reference Sequences). If an update command encounters an ambiguous Amplicon or Variant name, the command will fail and an error will be generated.

3.5.10.2

Renaming an Object

Although you can change most of the properties of an object using the update command (section 3.5.10.1), an object name change requires the “rename” command (see section 3.4.11 for the usage statement). For example:

rename sample –name Sample8 –newName Vial_XYZ

The general syntax of the rename command is: “rename <entity type> -name <existing name of entity> -newName <new name for entity>, whereby you provide the original name as the “name” parameter, and the name you want to change it to as the “newName” parameter. An alternative, more succinct, form of the command allows the “‑name” and “‑newName” option keywords to be left out with the old and new names being given positionally, as in:

rename sample Sample8 Vial_XYZ

As with the update command (section 3.5.10.1), if the Project contains Amplicons or Variants with duplicate names (but that are defined relative to different Reference Sequences), you must supply an “ofRef” parameter to specify which particular Amplicon or Variant you want to rename. If a rename command encounters an ambiguous Amplicon or Variant name, the command will fail and an error will be generated.

3.5.10.3

Removing an Object

If you find that you no longer have a need for an object, or if you find that an object you imported would require more work to edit than to create from scratch, you can use the “remove” command to eliminate it from the Project altogether (see section 3.4.10 for the usage statement). For example:

remove sample Sample8

Most of the remove commands have the syntax shown above, with the entity type and entity name as the only arguments to the command. Removing Amplicons and Variants, however, may also involve adding an extra “ofRef” parameter to resolve ambiguities where the Project contains Amplicons or Variants with duplicate names (but that are uniquely named relative to their particular Reference Sequences). If a remove command encounters an ambiguous Amplicon or Variant name, the command will fail and an error will be generated.

Be aware that removing an object can have a cascade of downstream consequences. If you delete a Read Data Set, the associations it has with any Sample-Amplicon sets will be severed (but the Samples will remain associated with the same Amplicons they had before the removal). Removing a Read Group will also remove all the Read Data Sets it contains (with the repercussions above). If you remove a Reference Sequence, you will also remove all the Amplicons and Variants associated with that Reference Sequence. Removing a Sample or an Amplicon severs any Read Data Set – Sample or Sample – Amplicon associations that it used to participate in. Removing a Variant does not impact other objects.

As for other commands, above, an asterisk (“*”) can be used in place of an entity name to mean all instances of an entity type. This allows you to easily remove all the entities of the specified type. You can combine the “ofRef” parameter with an asterisk to remove only those entities (Amplicons or Variants) from the specified Reference Sequence.

3.5.10.4

Dissociating Relationships

Sometimes, the objects you have entered into the Project are all correct, but you may have made the wrong associations between some of them; or, you may have cloned a previous Project with similar objects, but the new Project structure may be slightly different. In cases such as these, you would want to dissolve the incorrect associations without removing the objects from the Project. The “dissociate” command serves that purpose (see section 3.4.5 for the usage statement).

This command is used to influence the three-way Read Data Set – Sample – Amplicon relationships (as displayed in the Project Tab’s Read Data tree of the GUI) and the Sample-Amplicon relationships (displayed in the Project tab’s Samples tree of the GUI). As such, it has two general flavors: one primarily affects the Samples tree and the other, primarily the Read Data tree; but there can be changes in both trees as a result of either command type.

If you are primarily trying to influence the Sample-Amplicon relationships (as seen in the Samples tree), you should use the form of the command where you supply a Sample and an Amplicon as arguments. For example:

dissoc -sample Sample6 -amp EGFR_21_1

The command above removes the association between Sample6 and Amplicon EGFR_21_1 but does not remove either object from the Project. Additionally, while removing this association, any three-way Read Data Set – Sample – Amplicon associations for Sample 6 and EGR_21_1 would also be removed. In the GUI this would be reflected as elements being removed from the corresponding Read Data Sets of the Read Data tree.

If more than one Amplicons of the same name are associated with a Sample (but are uniquely named relative to their particular Reference Sequences), you must use the “‑ofRef” parameter to specify the Amplicon to which you want to apply the dissociation. If you don’t use the “‑ofRef” parameter in this situation, an error will be generated.

You can use an asterisk (“*”) as the Amplicon specifier in the command to dissociate all Amplicons from a Sample, with the concomitant dissociation of the related Read Data – Sample – Amplicon associations that may exist. The asterisk notation can be combined with the “‑ofRef” parameter to dissociate from the Sample all the Amplicons that are defined relative to a specified Reference Sequence (but maintain the associations of Amplicons from other Reference Sequences).

If you are primarily trying to influence the associations of a particular Read Data Set with its Samples and Amplicons, you should use the form of the command where you specify a Read Data, a Sample, and optionally an Amplicon as arguments. For example:

dissoc -readdata DGVS90J02 -samp Sample2 -amp EGFR_18_1

The command above dissociates the Read Data Set - Sample – Amplicon association triplet among DGVS90J02, Sample2, and EGFR_18_1, but all three objects still individually remain in the project. Dissociation of a Read Data Set - Sample – Amplicon triplet does NOT influence the corresponding Sample – Amplicon paired association, which is maintained.

If more than one Amplicon of the same name are associated with a Sample (but are uniquely named relative to their particular Reference Sequences), you must use the “‑ofRef” parameter to specify the Amplicon to which you want to apply the dissociation. If you don’t use the “‑ofRef” parameter in this situation, an error will be generated.

You can use an asterisk (“*”) as the Amplicon specifier in the command to dissociate all the Read Data Set - Sample – Amplicon triplets based on a given Read Data Set and Sample. As before, the dissociation of these triplet associations has no effect on the corresponding pairwise Sample-Amplicon relationships (as viewed in the Samples tree of the GUI). The asterisk notation can be combined with the “‑ofRef” parameter to dissociate only those Read Data - Sample – Amplicon triplets where the Amplicons are defined relative to a specified Reference Sequence (but maintain the associations for Amplicons from other Reference Sequences).

A shortened form of the Read Data-centric command allows you to omit the Amplicon specification and only supply a Read Data and a Sample. This is interpreted as if you had specified the Amplicon as an asterisk.

dissoc -readdata DGVS90J01 -samp Sample1