augur frequencies

Command-line arguments

infer frequencies of mutations or clades

usage: augur frequencies [-h] [--config CONFIG] --method {diffusion,kde}
                         --metadata FILE
                         [--metadata-delimiters METADATA_DELIMITERS [METADATA_DELIMITERS ...]]
                         [--metadata-id-columns METADATA_ID_COLUMNS [METADATA_ID_COLUMNS ...]]
                         [--regions REGIONS [REGIONS ...]]
                         [--pivot-interval PIVOT_INTERVAL]
                         [--pivot-interval-units {months,weeks}]
                         [--min-date MIN_DATE] [--max-date MAX_DATE]
                         [--tree TREE] [--include-internal-nodes]
                         [--alignments ALIGNMENTS [ALIGNMENTS ...]]
                         [--gene-names GENE_NAMES [GENE_NAMES ...]]
                         [--ignore-char IGNORE_CHAR]
                         [--minimal-frequency MINIMAL_FREQUENCY]
                         [--narrow-bandwidth NARROW_BANDWIDTH]
                         [--wide-bandwidth WIDE_BANDWIDTH]
                         [--proportion-wide PROPORTION_WIDE]
                         [--weights WEIGHTS]
                         [--weights-attribute WEIGHTS_ATTRIBUTE] [--censored]
                         [--minimal-clade-size MINIMAL_CLADE_SIZE]
                         [--minimal-clade-size-to-estimate MINIMAL_CLADE_SIZE_TO_ESTIMATE]
                         [--stiffness STIFFNESS] [--inertia INERTIA]
                         [--output-format {auspice,nextflu}] [--output OUTPUT]

Named Arguments

--config

config file path

--method

Possible choices: diffusion, kde

method by which frequencies should be estimated

--metadata

metadata including dates for given samples

--metadata-delimiters

delimiters to accept when reading a metadata file. Only one delimiter will be inferred.

Default: (',', '\t')

--metadata-id-columns

names of possible metadata columns containing identifier information, ordered by priority. Only one ID column will be inferred.

Default: ('id', 'strain', 'name')

--regions

region to filter to. Regions should match values in the ‘region’ column of the metadata file if specifying values other than the default ‘global’ region.

Default: ['global']

--pivot-interval

number of units between pivots

Default: 3

--pivot-interval-units

Possible choices: months, weeks

space pivots by months (default) or by weeks

Default: 'months'

--min-date

date to begin frequencies calculations; may be specified as:

  1. an Augur-style numeric date with the year as the integer part (e.g. 2020.42) or

  2. a date in ISO 8601 date format (i.e. YYYY-MM-DD) (e.g. ‘2020-06-04’) or

  3. a backwards-looking relative date in ISO 8601 duration format with optional P prefix (e.g. ‘1W’, ‘P1W’)

--max-date

date to end frequencies calculations; may be specified as:

  1. an Augur-style numeric date with the year as the integer part (e.g. 2020.42) or

  2. a date in ISO 8601 date format (i.e. YYYY-MM-DD) (e.g. ‘2020-06-04’) or

  3. a backwards-looking relative date in ISO 8601 duration format with optional P prefix (e.g. ‘1W’, ‘P1W’)

--tree, -t

tree to estimate clade frequencies for

--include-internal-nodes

calculate frequencies for internal nodes as well as tips

Default: False

--alignments

alignments to estimate mutations frequencies for

--gene-names

names of the sequences in the alignment, same order assumed

--ignore-char

character to be ignored in frequency calculations

Default: ''

--minimal-frequency

minimal all-time frequencies for a trajectory to be estimates

Default: 0.05

--narrow-bandwidth

the bandwidth for the narrow KDE

Default: 0.08333333333333333

--wide-bandwidth

the bandwidth for the wide KDE

Default: 0.25

--proportion-wide

the proportion of the wide bandwidth to use in the KDE mixture model

Default: 0.2

--weights

a dictionary of key/value mappings in JSON format used to weight KDE tip frequencies

--weights-attribute

name of the attribute on each tip whose values map to the given weights dictionary

--censored

calculate censored frequencies at each pivot

Default: False

--minimal-clade-size

minimal number of tips a clade must have for its diffusion frequencies to be reported

Default: 0

--minimal-clade-size-to-estimate

minimal number of tips a clade must have for its diffusion frequencies to be estimated by the diffusion likelihood; all smaller clades will inherit frequencies from their parents

Default: 10

--stiffness

parameter penalizing curvature of the frequency trajectory

Default: 10.0

--inertia

determines how frequencies continue in absense of data (inertia=0 -> go flat, inertia=1.0 -> continue current trend)

Default: 0.0

--output-format

Possible choices: auspice, nextflu

format to export frequencies JSON depending on the viewing interface

Default: 'auspice'

--output, -o

JSON file to save estimated frequencies to

Configuration

Options can also be specified in a YAML configuration file supplied to --config with the following top-level keys:

Option

Type

Description
method

one of:

  • diffusion
  • kde

method by which frequencies should be estimated
metadata

file

metadata including dates for given samples
metadata_delimiters

string(s)

delimiters to accept when reading a metadata file. Only one delimiter will be inferred.
metadata_id_columns

string(s)

names of possible metadata columns containing identifier information, ordered by priority. Only one ID column will be inferred.
regions

string(s)

region to filter to. Regions should match values in the ‘region’ column of the metadata file if specifying values other than the default ‘global’ region.
pivot_interval

integer

number of units between pivots
pivot_interval_units

one of:

  • months
  • weeks

space pivots by months (default) or by weeks
min_date

string or number

date to begin frequencies calculations; may be specified as:

  1. an Augur-style numeric date with the year as the integer part (e.g. 2020.42) or

  2. a date in ISO 8601 date format (i.e. YYYY-MM-DD) (e.g. ‘2020-06-04’) or

  3. a backwards-looking relative date in ISO 8601 duration format with optional P prefix (e.g. ‘1W’, ‘P1W’)
max_date

string or number

date to end frequencies calculations; may be specified as:

  1. an Augur-style numeric date with the year as the integer part (e.g. 2020.42) or

  2. a date in ISO 8601 date format (i.e. YYYY-MM-DD) (e.g. ‘2020-06-04’) or

  3. a backwards-looking relative date in ISO 8601 duration format with optional P prefix (e.g. ‘1W’, ‘P1W’)
tree

file

tree to estimate clade frequencies for
include_internal_nodes

boolean

calculate frequencies for internal nodes as well as tips
alignments

file(s)

alignments to estimate mutations frequencies for
gene_names

string(s)

names of the sequences in the alignment, same order assumed
ignore_char

string

character to be ignored in frequency calculations
minimal_frequency

number

minimal all-time frequencies for a trajectory to be estimates
narrow_bandwidth

number

the bandwidth for the narrow KDE
wide_bandwidth

number

the bandwidth for the wide KDE
proportion_wide

number

the proportion of the wide bandwidth to use in the KDE mixture model
weights

file

a dictionary of key/value mappings in JSON format used to weight KDE tip frequencies
weights_attribute

string

name of the attribute on each tip whose values map to the given weights dictionary
censored

boolean

calculate censored frequencies at each pivot
minimal_clade_size

integer

minimal number of tips a clade must have for its diffusion frequencies to be reported
minimal_clade_size_to_estimate

integer

minimal number of tips a clade must have for its diffusion frequencies to be estimated by the diffusion likelihood; all smaller clades will inherit frequencies from their parents
stiffness

number

parameter penalizing curvature of the frequency trajectory
inertia

number

determines how frequencies continue in absense of data (inertia=0 -> go flat, inertia=1.0 -> continue current trend)
output_format

one of:

  • auspice
  • nextflu

format to export frequencies JSON depending on the viewing interface
output

string

JSON file to save estimated frequencies to