Parent / Descendant Tracking

Many documents in Geneious Prime are the output of an operation run on a set of input documents. The input documents of the operation are known as the parents of the output, and the output documents the descendants (or children) of the input. Those parent documents may themselves be the descendants of other documents, each with their own parents, and so on. In many situations it is useful to preserve this hierarchy, so that future alterations, for example the re-calling of a base, or the addition of a new annotation, can be transferred downstream to the molecules affected by this change in a parent.

An active link between a child and its parents means that when you modify any of the parent documents, you will be given the choice of propagating these changes to the child. When this modification affects a part of the parent involved in creating the child, the change will be immediately visible in the child. Modifications include things like editing the residues of a sequence, adding new annotations, or changing the meta-data associated with the document.

Propagating a change to a parent document causes Geneious to rerun every operation that links that parent actively to one or more child documents, with the altered parent document (and any other parents) as input. Geneious stores the options that the operation was originally run with so that it can reproduce the original operation's conditions exactly, and afterwards matches up the newly regenerated child documents with any former children, and replace their contents where possible.

Occasionally, one or more of the parent documents has been altered to a point where an operation can no longer be rerun, or a necessary parent document is inaccessible. In this case, Geneious will inform you of the failure, and attempt to be as specific as possible about the cause of the failure. For example in the figure below the "Extract PCR product" operation can't be propagated because one of the primers has been removed.

Inactive links do not propagate changes from parent to child. Inactive links are created in two different ways; firstly, when you choose not to propagate changes, that active link becomes temporarily inactive. Secondly, if an operation does not support creation of active links, or was told not to create them, all links between its parents and children will be permanently inactive. All operations in Geneious Prime at least create inactive links.

The following operations in Geneious Prime can produce actively linked documents:

• Cloning: Digest into Fragments, Ligate Sequences, Restriction Cloning, Gibson Assembly, Gateway Cloning, Golden Gate, TOPO Cloning
• Primers: Extract PCR product
• Sequence Viewer: Paste with Active Link from the right click menu (see copy-paste cloning)
• Sequence Viewer: Extract and Translate

Note: Extract and Translate will not create active links by default. To do so, you must select the Actively link source and extracted documents checkbox in the relevant dialog, otherwise they will be created with permanently inactive links.

Editing Linked Parent Documents

When you make changes to a document that is the parent of another document, you will be given the opportunity to either propagate the changes to the descendants, deactivate the link (which can later be reactivated, see Lineage View), or save the changed document as a new copy. You may also simply back out of this process by choosing to cancel, which will return you to your unsaved changes. Note that if you choose to deactivate the link, this dialog will not be displayed upon subsequent saves of the parent document, unless the link is reactivated again at some future time.

In order to aid with your decision making, the dialog allows you to view the document's descendants in a smaller, cut down version of the Lineage View. Pressing the View Descendants button will bring up this view:

Editing Linked Child Documents

Only annotation modifications can be propagated from descendant (child) documents back to their parents. If you make a non-annotation edit, such as an edit to the sequence itself, you will immediately be warned that in order to save your changes you will need to deactivate this link. As with the Actively Linked Descendants view, you will be given the opportunity to view the document's lineage. Editing a document that is a descendant of other documents is usually unintentional; however, in some circumstances you may simply be interested in the output documents of an operation (not the parent-descendant relationship), and as such you may hide this dialog:

Editing annotations on linked child documents

Annotations on actively linked child documents can be added, deleted or edited without breaking links to the parent document. However, there are some limitations to this:

• If residues in the parent document are modified in a way that makes it unclear where the annotations belong on the child document they might disappear (e.g. the residues in the parent document are deleted and the changes are propagated to the child).

• If an annotation is deleted from a child document then the same annotation is modified on the parent document, the annotation will reappear on the child document.

• An annotation which is deleted from a child will remain deleted on the child if the parent annotation is deleted and an identical annotation recreated on the parent.

• An annotation which is edited on a child and then edited on a parent, will diverge into two separate annotations.

If you try to add, delete or edit an annotation on a child document, you will be warned that you must choose whether to keep links, deactivate links or save a copy to keep your changes

If you choose to Continue Annotation Editing and then save your changes to the child document you will be asked whether you want to keep the links active, deactivate the links or save a copy without the parents.

Keep active links to parents will allow you to maintain the lineage, but you might lose the annotations on your child document if the parent document is edited in a way that causes the annotation on the child to become unclear, as explained above. An active link note (as shown below) will be added to any annotation added or edited on a child document that retains the active link to its parent.

Deactivate links to parents will save the annotation changes to your child document, but will deactivate the links to the parent so that any changes you make to parent documents will no longer be propagated to the child.

Save as copy without parents will preserve the original file with the links to the parents. The original linked file will not contain your edited annotations if you choose this option, but the saved copy will bear your annotation modifications and will no longer be linked to the parent document.

The Lineage View

Every document that is linked (actively or otherwise) to another document has a tab called Lineage above the sequence viewer. The lineage view allows you view parent-descendant relationships, manage links, and navigate between documents.

All active links appear as green text, whilst inactive links appear as black text and the document currently being viewed (and which is the root of the parents tree and the descendents tree) appears in blue. Each's document's name is displayed along with an icon (similar to the document table) denoting what type of sequence it is.

Also displayed in the viewer are the operations that generated each set of children, along with the time at which the operation was run and the type of operation. For supported cloning operations, the options used when an operation was run can be viewed by clicking the Show Options button. If preferred, operations can be hidden by unchecking the Show Operations checkbox, providing a layout which is akin to Vector NTI. You can also choose to view only active links by unchecking the Show Inactive Links checkbox. This will hide all inactively linked documents, as well as those documents' parents or descendants. This means that you will only be viewing documents that are directly affected by one currently being viewed.

You can reactivate temporarily deactivated links from the view by right-clicking (Windows, Linux) or control-clicking (MacOS) on a document and choosing Activate link to parent/child from the context menu.

Alternatively you can reactivate links to all children at once by choosing Show Operations and right- or control-clicking on the operation, then selecting Reactivate all links for this operation. You may also manually deactivate links in this fashion.

Note: reactivating links immediately reruns the operation; depending on the size and type of the operation, this can be time consuming. Also note that reactivating will cause any unsaved changes to any direct or indirect descendants to be overwritten, since this involves a complete recompute from the parent documents. You will be warned about this before Geneious allows you to reactivate.

To export the currently selected document (highlighted in blue in the view) directly from the lineage view, use the Export Documents button.

From here you can choose to export parents or descendants only, or both, as well as choose to export only those documents that are actively linked in the hierarchy. Similarly to how unchecking the "Show Inactive Links" checkbox works, unchecking "Inactively linked documents" here will mean that the export will stop as soon as it finds in inactively linked parent or descendant (depending on the relevant direction), and stop exporting down that branch of the lineage.

The Save as HTML option saves the parent and descendant trees as a bulleted list in html format, allowing you to open the contents of the lineage view in a web browser.