Exporting from the Project

3.5.14

It can be convenient to use aspects, or the entire definition, of an existing Project as the basis for defining a new Project. Two utility commands are available (“utility makeSetupScript” and “utility clone”) that provide the means to export most or all aspects of an existing Project definition at once; and a set of “list” commands are provided to facilitate more focused exports of Project setup data.

3.5.14.1

utility makeSetupScript

The “utility makeSetupScript” command is basically a means of making a backup of the setup of your currently open Project in the CLI (see section 3.4.17.3 for the usage statement). If you provide the command with an “‑outputFile” option, the CLI writes a script to that file that contains all the commands that you would have to input to doAmplicon to regenerate your Project setup.

The script will contain commands to create the Project directory structure and to create all the Project objects and the required associations between them. Load commands are included to handle the import of the Read Data Sets. However, the script does not back up any computed results for the Project. Generally, you will not be able to run the script immediately after you generate it, because your Project will still be in place and the “create Project” command in the script will fail because you can’t create a Project that already exists. The script is intended as a safety measure that you could use to reconstitute your Project should the Project directory become corrupted. Note that the “utility makeSetupScript” command exports the Project setup based on the state of the open Project that you have in memory when you run the command (including any unsaved changes). The load commands generated for the Read Data Sets will try to find the data in the original locations where the data was located when originally imported into the Project (whether via the CLI or the GUI). If that data has been moved to a new location, you will need to manually edit the setup script to reflect the new location. If the data is no longer available, the load commands will fail. Note that the script only backs up the Project setup; it does not backup of the actual Read Data Sets.

3.5.14.2

utility clone

The “utility clone” command is used to create an exact copy of a Project setup to another location (see section 3.4.17.4 for the usage statement). The command is used in the context of an open Project in the CLI, and you provide the location where you want the clone to be created (e.g., “utility clone /data/clonedProjectDirectory”). The command copies the Project directory structure and objects with their associations to the new location, but does not copy the Read Data Sets (unless specifically called for by setting the “‑copyReadData” parameter to “true”).

A “‑scriptOnly” option can be used to prevent the actual execution of the clone operation and instead write out the commands necessary to carry out the cloning process to a script that you can edit and use later as input to a doAmplicon command (this is similar to running the “utility makeSetupScript” command, except that the Read Data Sets are not copied by default). The clone operation uses the state of the open Project at the time the command is run, so any unsaved changes involving the Project setup will be included in the clone operation. The cloning operation does not include any computed results for the Project.

If you choose to copy the Read Data Sets as part of the clone command, the read data will be obtained from the open Project and then the “OriginalPath” of the Read Data Sets will be updated to reflect the true original source of the data. This allows the clone to occur even if the original source of the Read Data Sets has been moved or deleted. The read data import should only fail if there are disk space issues or if the Project being cloned uses symbolic links and the links are invalid because the data was moved or deleted.

3.5.14.3

list

Sometimes you may want to export only a specific subset of the Project setup data rather than backing up or cloning an entire Project. Examples may be that you want to reuse some Reference Sequences from one Project in a new Project; or that you want to recycle some Amplicons and/or Variants associated with those Reference Sequences, but you don’t want to import any Samples or Sample – Amplicon relationships (e.g. because your new Project will have its own Samples, different from the ones of the existing Project). In these cases you can use the “list” command to output tabular data that is suitable to import into a new Project (see section 3.4.7 for the usage statement). The tables returned by the list command can have their format set to tab-separated values (tsv) or comma-separated values (csv). Using the “‑outputFile” option, you can specify what file the table should be written to or you can allow the table to be written to standard output.

To import a list table into a new Project, use the corresponding create command for the data type in the file, and either provide the table file using the “‑file” parameter or the contents of the file as part of a “here” format file (e.g., “create ref ‑file listRefTable.tsv”, where listRefTable.tsv was previously created from another project via “list ref ‑outputFile listRefTable.tsv”).

The list commands can also be useful in interactive mode as a way to verify the content of the Project as you enter and edit Project objects. Even if you aren’t in interactive mode, the list commands can be used in scripts to enhance logging in scripts when troubleshooting.

List commands are available to review and export the basic entities of the Project, but not the associations between Samples, Amplicons, and Read Data Sets managed by the associate command. To view or export those associations one must inspect or run the scripts generated by the “utility makeSetupScript” and “utility clone” commands.