Interacting with Projects - giffordlabcvr/Parvovirus-GLUE GitHub Wiki

1. The GLUE Engine and Command Layer

GLUE contains an interactive command layer that serves as its public interface, enabling users (and client programs) to manipulate data in GLUE projects. The command layer provides a range of productivity-oriented features such as automatic command completion, command history and interactive paging through tabular data.

Projects within GLUE are structured according to an underlying data model, and users interact with data objects using a command-line interface (the GLUE console).

The GLUE console operates based on the mode path, which reflects the current position within the data model. Depending on your position in the data model, different commands become available.

For example, in the root mode path (i.e. Mode path: /), the list command is available for listing projects.

Mode path: /
GLUE> list project 
+==============+========================================+
|     name     |              description               |
+==============+========================================+
| parvoviridae | A GLUE project for the Parvoviridae    |
+==============+========================================+
Projects found: 1

2. Navigation

You can navigate into a specific data object, such as the parvoviridae project, via the GLUE console. For example, if you type the following command and press return, the mode path will update as shown:

Mode path: /
GLUE> project parvoviridae
OK
Mode path: /project/parvoviridae

Under this mode path, tab command completion reveals new options for the list command, reflecting the data model.

GLUE> list 
alignment           almt-member         custom-table-row    feature             
feature-location    format              member-floc-note    module              
reference           sequence            source              var-almt-note       
variation

We can also navigate into alignment objects, as shown here:

Mode path: /project/parvoviridae
GLUE> alignment AL_GENUS_Proto
OK
Mode path: /project/parvoviridae/alignment/AL_GENUS_Proto

This will make new command options available - as revealed by tab command completion:

Mode path: /project/parvoviridae/alignment/AL_GENUS_Proto
GLUE> 
add                amino-acid         clear              commit             config             
console            count              data-util          demote             derive             
descendent-tree    exit               export             extract            file-util          
glue-engine        help               list               member             new-context        
project-mode       quit               remove             render-object      root-mode          
run                score              set                show               unset              
variation          web-list

Exiting a Level: To move up one level in the data model:

GLUE> exit

You will return to the previous level:

Mode path: /project/parvoviridae

Shortcut to Project or Root Levels: To return directly to the project or root level:

GLUE> project-mode
Mode path: /project/parvoviridae/

GLUE> root-mode
Mode path: /

3. Executing Commands

The command line interface provides a means to interact with project data items. For example, alignments can be listed using the following command:

GLUE> project parvoviridae list alignment -s parent.displayName name clade_category parent.displayName
+===============================+================+============================+
|             name              | clade_category |     parent.displayName     |
+===============================+================+============================+
| AL_SUBFAMILY_Densovirinae     | Subfamily      | Family Parvoviridae        |
| AL_SUBFAMILY_Hamaparvovirinae | Subfamily      | Family Parvoviridae        |
| AL_SUBFAMILY_Parvovirinae     | Subfamily      | Family Parvoviridae        |
| AL_GENUS_Ambidenso            | Genus          | Subfamily Densovirinae     |
| AL_GENUS_Aquiambidenso        | Genus          | Subfamily Densovirinae     |
| AL_GENUS_Blattambidenso       | Genus          | Subfamily Densovirinae     |
| AL_GENUS_Iteradenso           | Genus          | Subfamily Densovirinae     |
| AL_GENUS_Miniambidenso        | Genus          | Subfamily Densovirinae     |
| AL_GENUS_Pefuambidenso        | Genus          | Subfamily Densovirinae     |
| AL_GENUS_Protoambidenso       | Genus          | Subfamily Densovirinae     |
| AL_GENUS_Scindoambidenso      | Genus          | Subfamily Densovirinae     |
| AL_GENUS_Brevidenso           | Genus          | Subfamily Hamaparvovirinae |
| AL_GENUS_Hepandenso           | Genus          | Subfamily Hamaparvovirinae |
| AL_GENUS_Penstyldenso         | Genus          | Subfamily Hamaparvovirinae |
| AL_SUPERGENUS_Chaph_Ichth     | Supergenus     | Subfamily Hamaparvovirinae |
| AL_SUPERGENUS_Amdo_Proto      | Supergenus     | Subfamily Parvovirinae     |
| AL_SUPERGENUS_Ave_Boca        | Supergenus     | Subfamily Parvovirinae     |
| AL_SUPERGENUS_DECTA           | Supergenus     | Subfamily Parvovirinae     |
| AL_GENUS_Amdo                 | Genus          | Supergenus Amdo-Proto      |
| AL_GENUS_Proto                | Genus          | Supergenus Amdo-Proto      |
| AL_GENUS_Ave                  | Genus          | Supergenus Ave-Boca        |
| AL_GENUS_Boca                 | Genus          | Supergenus Ave-Boca        |
| AL_GENUS_Chaphama             | Genus          | Supergenus Chap-Icth       |
| AL_GENUS_Ichthama             | Genus          | Supergenus Chap-Icth       |
| AL_GENUS_Arti                 | Genus          | Supergenus DECTA           |
| AL_GENUS_Copi                 | Genus          | Supergenus DECTA           |
| AL_GENUS_Dependo              | Genus          | Supergenus DECTA           |
| AL_GENUS_Erythro              | Genus          | Supergenus DECTA           |
| AL_GENUS_Tetra                | Genus          | Supergenus DECTA           |
+===============================+================+============================+
Alignments found: 29

Command Breakdown

Command: project parvoviridae list alignment -s parent.displayName name clade_category parent.displayName
- project parvoviridae: Sets the active project to 'parvoviridae', meaning all subsequent commands apply to this project.
- list alignment: Lists all alignments defined in the project.
- -s parent.displayName: Sorts the output by the parent.displayName field, which represents the display name of the parent alignment.
- name clade_category parent.displayName: Specifies the fields to display in the output:
  - name: The name of each alignment.
  - clade_category: The taxonomic category (e.g., Subfamily, Genus, Supergenus) assigned to the alignment.
  - parent.displayName: The display name of the parent alignment, which provides hierarchical context.

Output Breakdown

Table Headers:
- name: The unique identifier of the alignment.
- clade_category: Indicates the taxonomic rank of the alignment (e.g., Subfamily, Genus).
- parent.displayName: Shows the name of the parent alignment that categorizes the current alignment.
Sorting:
- The output is sorted by the parent.displayName field. This means that alignments are grouped and listed in order based on their parent alignments' display names.
Output Rows:
- Each row represents an alignment within the 'parvoviridae' project.
- The rows are grouped by their parent alignment, and within each group, the specific alignments are listed along with their clade category.