command line interface

[andrewkern]

hey all-- i've been helping a student use hyphy with a project and we came to a place where we wanted to use the CLI in a non-interactive way. i was having a bit of a hard time finding how to do this in the documentation, and so with a bit of reverse engineering stumbled upon CLI syntax like this, essentially feeding the desired parameters of the analysis as positional variables.

hyphy acd Universal <alignment.fa> MG94CUSTOMCF3X4 Global 012345 <treefile> Estimate

is this officially supported? is it documented somewhere for me to share with others? I'd be happy to contribute some docs here if that would be helpful.

cheers, Andy

[spond]

Dear @andrewkern,

There are two levels of CLI argument support. Most newer (post 2015 or so) analyses will have keyword-style arguments, and you can see what they are by typing hyphy analysis --help where analysis is the name of the analysis.

For example,

hyphy gard --help 

Available analysis command line options
---------------------------------------
Use --option VALUE syntax to invoke
If a [reqired] option is not provided on the command line, the analysis will prompt for its value
[conditionally required] options may or not be required based on the values of other options

type
    The type of data to perform screening on
    default value: nucleotide

code
    Genetic code to use (for codon alignments)
    default value: Universal
    applies to: Choose Genetic Code

alignment [required]
    Sequence alignment to screen for recombination

model
    The substitution model to use
    default value: JTT

rv
    Site to site rate variation
    default value: None

max-breakpoints
    Maximum number of breakpoints to consider
    default value: 10000

rate-classes
    How many site rate classes to use
    default value: 4

output
    Write the resulting JSON to this file (default is to save to the same path as the alignment file + 'GARD.json')
    default value: gard.defaultJsonFilePath [computed at run time]

mode
    Run mode (Normal or Faster)
    default value: Normal

output-lf
    Write the best fitting HyPhy analysis snapshot to (default is to save to the same path as the alignment file + 'best-gard')
    default value: gard.defaultFitFilePath [computed at run time]

They you can do something like hyphy gard --alignment /path/to/file --rv GDD --mode Faster --rate-casses 3

For OLDER analyses (like acd) if you tried the same approach you'd get nothing

hyphy acd --help 

Available analysis command line options
---------------------------------------
Use --option VALUE syntax to invoke
If a [reqired] option is not provided on the command line, the analysis will prompt for its value
[conditionally required] options may or not be required based on the values of other options

No annotated keyword arguments are available for this analysis

However, as you discovered, simply listing analysis arguments in FIFO order on the command line will be treated as providing them positionally.

One key difference is that the latter (positional) approach will terminate with an error if you don't supply all the arguments. The keyword argument approach, on the other hand, will use the values you supplied, and if a required argument is not given, the program will prompt the user for it interactively.

HTH, Sergei

[andrewkern]

thanks @spond! it might be helpful to document the FIFO positional approach too as it's really convenient, if old school 😄

[spond]

Dear @andrewkern,

Yes, indeed. Documentation is always the very last thing we do, isn't it?

@stevenweaver : can I ask you to make a note of it somewhere on hyphy.org?

Best, Sergei

[andrewkern]

Happy to help in some way if I can. It would be awesome for GitHub denizens like me if the readme on the repo had such info as well- maybe I could submit a PR there?

[spond]

Dear @andrewkern,

That'd be wonderful and I would definitely welcome and encourage it!

Best, Sergei