-
Notifications
You must be signed in to change notification settings - Fork 4
Reference package operations
TreeSAPP's reference packages are formatted as a single, compressed file known as a pickle (.pkl extension). Because they are compressed, they are not human-readable and therefore could be a bit of a black box.
With the command treesapp package, these become not just viewable but also mutable. The three subcommands of treesapp package are view, edit and rename. The usage of all three is very similar in that the same command-line arguments can be provided to these commands. However, it is worth going over some key differences.
Supported versions >=0.9.7
usage: treesapp package [-v] [-h] -r PKG_PATH [PKG_PATH ...] [-o OUTPUT]
[--overwrite]
[{view,edit,rename}] attributes [attributes ...]
Facilitate operations on reference packages
positional arguments:
{view,edit,rename} A subcommand specifying the type of operation to
perform. `treesapp package rename` must be followed
only by 'prefix' and the new value. Example: `treesapp
package rename prefix Xyz -r path/to/Xyz_build.pkl`
Required parameters:
-r PKG_PATH [PKG_PATH ...], --refpkg_path PKG_PATH [PKG_PATH ...]
Path to the reference package pickle (.pkl) file.
attributes One or more reference package attributes to view.
Note: edit will only modify a single attribute at a
time. Choices include: boot_tree, cmd, date,
description, f__boot_tree, f__json, f__model_info,
f__msa, f__profile, f__search_profile, f__tree, kind,
lineage_ids, model_info, molecule, msa, num_seqs,
pfit, pid, prefix, profile, profile_length,
refpkg_code, refpkg_suffix, search_profile, sub_model,
tree, tree_tool, ts_version, update
Optional options:
-o OUTPUT, --output OUTPUT
Path to an output directory. Default is the current
working directory.
--overwrite When editing a reference package, should the current
file be overwritten?
Miscellaneous options:
-v, --verbose Prints a more verbose runtime log
-h, --help Show this help message and exit
treesapp package view is used to read different attributes of a reference package. By default these are printed to the console window via standard out, meaning these could be piped to other UNIX commands (e.g. awk and sed).
Run treesapp package view -h to get the complete list of attributes that can be printed by view. These are under the 'attributes' argument, as shown above. view is able to show multiple attributes from the same command by including different attribute names separated by spaces. For example, to print the name, reference package code, TreeSAPP version, and description of the reference package found at Photosynthesis/PuhA/seed_refpkg/final_outputs/PuhA_build.pkl
$ treesapp package view prefix refpkg_code ts_version description -r Photosynthesis/PuhA/seed_refpkg/final_outputs/PuhA_build.pkl
prefix PuhA
refpkg_code P0001
ts_version 0.9.5
description
TreeSAPP has finished successfully.
treesapp package edit is used to modify reference package attributes. If you've already used treesapp create to build a reference package, chances are you've already used this to change the refpkg_code attribute of your new reference package.
Unlike view, edit will only accept -- and therefore modify -- a single attribute. The edited reference package can be written to a new directory or overwrite the original reference package. Warning: the reference package will be named based on the 'prefix' attribute and the argument '--output' specifies a directory path. Therefore, writing to the same directory of the original reference package could have unintended consequences!
To write a new reference package pickle for PuhA with it's 'description' attribute modified, you could use
treesapp package edit description 'Photosynthetic reaction center subunit H' -r Photosynthesis/PuhA/seed_refpkg/final_outputs/PuhA_build.pkl --output ~/Desktop/
treesapp package rename is a special reference package editing operation where multiple attributes are modified to match the new name (really, the 'prefix' attribute) of a reference package.