associate

3.4.1

    assoc[iate] -sam[ple] <sample name>

                -amp[licon] <amplicon name> [-ofRef <reference sequence name>]

                [-file <file> [-format <format>]]

    assoc[iate] -sam[ple] <sample name>

                -readData <read data name> | -readGroup <read group name>

                [-file <file> [-format <format>]]

    assoc[iate] -sam[ple] <sample name>

                -amp[licon] <amplicon name> [-ofRef <reference sequence name>]

                -readData <read data name> | -readGroup <read group name>

                [-file <file> [-format <format>]]

    assoc[iate] -mul[tiplexer] <multiplexer name>

                [-primer1Mid <primer1Mid name>

                    [-ofPrimer1MidGroup <primer1MidGroup name>]]

                [-primer2Mid <primer2Mid name>

                    [-ofPrimer2MidGroup <primer2MidGroup name>]]

                -checkMid <boolean>

                [-file <file> [-format <format>]]

    assoc[iate] -mul[tiplexer] <multiplexer name>

                [-primer1Mid <primer1Mid name>

                    [-ofPrimer1MidGroup <primer1MidGroup name>]]

                [-primer2Mid <primer2Mid name>

                    [-ofPrimer2MidGroup <primer2MidGroup name>]]

                -checkMid <boolean>

                -sam[ple] <sample name>

                [-file <file> [-format <format>]]

    assoc[iate] -mul[tiplexer] <multiplexer name>

                -amp[licon] <amplicon name> [-ofRef <reference sequence name>]

                -readData <read data name> | -readGroup <read group name>

                [-file <file> [-format <format>]]

    assoc[iate] -mul[tiplexer] <multiplexer name>

                -readData <read data name> | -readGroup <read group name>

                [-file <file> [-format <format>]]

    assoc[iate] -mul[tiplexer] <multiplexer name>

                [-primer1Mid <primer1Mid name>

                    [-ofPrimer1MidGroup <primer1MidGroup name>]]

                [-primer2Mid <primer2Mid name>

                    [-ofPrimer2MidGroup <primer2MidGroup name>]]

                -checkMid <boolean>

                -sam[ple] <sample name>

                -amp[licon] <amplicon name> [-ofRef <reference sequence name>]

                -readData <read data name> | -readGroup <read group name>

                [-file <file> [-format <format>]]

    The 'associate' command is used to associate records in many-to-many

    relationships.  Such relationships can exist between samples, amplicons,

    read data, multiplexers, and MIDs.  When a particular association is made,

    any more general associations that would be logically implied by the

    original association will automatically be created (e.g., associating the

    triplet of a sample, amplicon, and read data will implicitly create the

    pairwise sample-amplicon association as well).

    In any of the command forms above where '-amplicon' is being specified,

    the '-ofRef' option can be used to disambiguate amplicons with the same

    name but which are from different reference sequences.

    The '-amplicon' option may be specified as a "*" to allow multiple

    amplicons to be associated with a single command.  If a "*" is passed as

    the '-amplicon' option value, with no '-ofRef' option, the "*" is

    interpreted to indicate that all of the amplicons known in the project at

    the time of the invocation will be involved in the association.  If both

    the "*" value and '-ofRef' option are used, then all amplicons in the

    project at the time of invocation that are of the given reference sequence

    will be involved in the association.

    In a similar manner to the '-ofRef' option for amplicons, the

    '-ofPrimer1MidGroup' and '-ofPrimer2MidGroup' options can be used to

    disambiguate '-primer1Mid' and '-primer2Mid' specifications, respectively.

    The '-primer1Mid' and '-primer2Mid' options may also be specified as a

    "*".  If no '-ofPrimer1MidGroup' or '-ofPrimer2MidGroup' option is

    supplied, the "*" refers to all the MIDs of the project.  If a MID group

    is specified, the "*" refers to only the MIDs of that MID group.

    The '-checkMid' option is used to verify that the MIDs associated with the

    primer1 side of the multiplexer are all mutually compatible as are the

    primer2 side MIDs.  The definition of compatibility is the same as that

    used by the '-checkMidGroup' option of the 'create mid' command (defined

    sequences are compatible if they are of the same length and are

    non-identical, with undefined zero-length sequences allowed).  This option

    must be 'true' or 'false', and defaults to 'true' if not provided.

    Read data can be specified in a command as either a specific read data

    using the '-readData' option or as a collection of read data using the

    '-readGroup' option.  When '-readGroup' is used, it is as if the command is

    being run multiple times (once for each particular read data in the read

    group at the time of invocation).  For example, if readGroup1 has 3

    read data in it (readData1, readData2, and readData3), running the command:

        associate -sample sample1 -readGroup readGroup1

    and running the commands:

        associate -sample sample1 -readData readData1

        associate -sample sample1 -readData readData2

        associate -sample sample1 -readData readData3

    would have the same net effect.  In those situations where identical

    associations can correctly be made with each of the read data in a read

    group, the '-readGroup' allows the command to be more concise.

    Explanations of the various command forms are as follows:

    Run 'help general tabularCommands' for information about the '-file'

    option.

    assoc[iate] -sam[ple] <sample name>

                -amp[licon] <amplicon name> [-ofRef <reference sequence name>]

                [-file <file> [-format <format>]]

    When only a sample and amplicon are specified, an association is created

    between them.  The '-ofRef' option can be used to disambiguate amplicons

    with the same name that refer to different reference sequences.  If a "*"

    is passed as the '-amplicon' option value, with no '-ofRef' option, all

    amplicons known in the project are associated with the sample.  If both the

    "*" value and '-ofRef' option are used, then all amplicons of the given

    reference sequence are associated with the sample.

    assoc[iate] -sam[ple] <sample name>

                -readData <read data name> | -readGroup <read group name>

                [-file <file> [-format <format>]]

    When a sample and read data are specified, associations are created between

    the sample itself, all of the current amplicons associated with the sample,

    and the read data.  For example, running

        associate -sample sample1 -readData read1

    will associate "sample1" and all of its amplicons at the time of invocation

    with "read1".

    Similarly, when a sample and read group are specified, associations are

    created between the sample itself, all of the current amplicons associated

    with the sample, and all of the read data in the read group.  For example,

    running

        associate -sample sample1 -readGroup group1

    will associate "sample1" and all of its amplicons at the time of invocation

    with all of the read data in "group1".

    assoc[iate] -sam[ple] <sample name>

                -amp[licon] <amplicon name> [-ofRef <reference sequence name>]

                -readData <read data name> | -readGroup <read group name>

                [-file <file> [-format <format>]]

    If a sample, an amplicon, and read data are specified, an association is

    created between the sample itself, the amplicon, and the read data.  The

    '-ofRef' option can be used to disambiguate amplicons with the same name

    that refer to different reference sequences.  If a "*" is passed as the

    '-amplicon' option value,  with no '-ofRef' option, all amplicons known

    in the project are associated with the sample and read data.  If both the

    "*" value and '-ofRef' option are used, then all amplicons of the given

    reference sequence are associated with the sample and read data.  If a read

    group is specified instead of a single read data, the sample and

    amplicon(s) are associated with all of the read data in the read group.

    In general, creating a triplet association between an amplicon, sample

    and some read data implicitly creates a simultaneous paired association

    between the amplicon and sample.  If an amplicon is already associated

    with some sample on a particular read data set, any attempt to associate

    the amplicon with a different sample on the same read data set will be

    ignored (but with a warning) since the demultiplexing constraints only

    allow amplicons to be associated with individual samples in the context

    of any individual read data set (an amplicon may be associated with

    different samples on different read data sets, and different amplicons

    may be associated with different samples on the same read data, however).

    assoc[iate] -mul[tiplexer] <multiplexer name>

                [-primer1Mid <primer1Mid name>

                    [-ofPrimer1MidGroup <primer1MidGroup name>]]

                [-primer2Mid <primer2Mid name>

                    [-ofPrimer2MidGroup <primer2MidGroup name>]]

                -checkMid <boolean>

                [-file <file> [-format <format>]]

    When some combination of MIDs and a multiplexer are specified, the MIDs

    will be associated with the multiplexer.  For either of the MID options

    ('-primer1Mid' and '-primer2Mid'), all of the MIDs in the project may be

    specified at the same time by using a "*" for the value.  The

    '-ofPrimer1MidGroup' and '-ofPrimer2MidGroup' options can be used to

    restrict the "*" set of MIDs to those of a particular MID group (or to

    disambiguate MIDs with the same name from different MID groups).  If it

    becomes necessary to temporarily associate inconsistent MIDs on a primer

    MID side, '-checkMid' can be set to 'false'.

    Although it might be a more common case to use the next command below to

    simultaneously associate a multiplexer, MIDs, and a sample in a single

    operation (letting the implied multiplexer-MID associations be made

    automatically), the above command can be useful to specify MIDs that are

    not explicitly tied to samples.  In particular, if compatible MIDs have

    been used in recent experiments, but are not present in this experiment,

    associating them to the multiplexer without samples can help prevent

    potential contaminants from being assigned to samples of this experiment.

    assoc[iate] -mul[tiplexer] <multiplexer name>

                [-primer1Mid <primer1Mid name>

                    [-ofPrimer1MidGroup <primer1MidGroup name>]]

                [-primer2Mid <primer2Mid name>

                    [-ofPrimer2MidGroup <primer2MidGroup name>]]

                -checkMid <boolean>

                -sam[ple] <sample name>

                [-file <file> [-format <format>]]

    When some combination of MIDs, a multiplexer, and a sample are specified,

    the sample is associated with a particular MID configuration of the

    multiplexer.  There are restrictions on how the MID options ('-primer1Mid'

    and '-primer2Mid') can be used that depend on the '-encoding' type of the

    multiplexer.  If the encoding type is 'both', it is required that both MID

    options be provided in order to associate the sample with a pair of MIDs.

    If the encoding type is 'either', 'primer1', or 'primer2', it is only

    necessary to supply one of the MID options at a time.  In the 'either'

    case, specifying both options at the same time is allowed.  In the

    'primer1' and 'primer2' cases, the MID option of the proper type must be

    used (e.g., the 'primer1' encoding type requires that the '-primer1Mid'

    option be used).  Any implied multiplexer-MID associations that were not

    explicitly set up previously will automatically be created as a consequence

    of this command.  A sample may be associated with more than one MID

    configuration, but each MID configuration may only map to a single sample

    (e.g., in an 'primer1' configuration, sample1 may be associated with both

    MID1 and MID2 on the primer1 side, but those MIDs could not simultaneously

    be associated with a different sample2).

    assoc[iate] -mul[tiplexer] <multiplexer name>

                -amp[licon] <amplicon name> [-ofRef <reference sequence name>]

                -readData <read data name> | -readGroup <read group name>

                [-file <file> [-format <format>]]

    When a multiplexer, amplicon and read data are specified, the amplicon will

    be associated with the read data-multiplexer context.  As a result, the

    amplicon automatically becomes associated with each of the samples

    associated with the multiplexer (creating any missing sample-amplicon

    relationships along the way).  A "*" may be provided with the '-amplicon'

    option to indicate that all amplicons in the project should be associated.

    The '-ofRef' option can be used, if necessary, to disambiguate amplicons

    with the same name or to restrict the "*" set of amplicons to those of the

    specified reference sequence.  The association may be made with a single

    read data using the '-readData' option, or the associations can be made

    at once for all of the read data within a read group using the '-readGroup'

    option.  Multiplexers may be associated with several different read data

    sets.  Each of those read data-multiplexer contexts are allowed to have

    different amplicon associations, but the internal MID-sample associations

    remain the same in each of those contexts.  If the  multiplexer is not

    already associated with the specified read data when this command is

    invoked, those read data-multiplexer associations are created

    automatically.

    assoc[iate] -mul[tiplexer] <multiplexer name>

                -readData <read data name> | -readGroup <read group name>

                [-file <file> [-format <format>]]

    When a multiplexer and a read data are specified, the association between

    the pair is created.  This provides a read data-multiplexer context that is

    ready to accept amplicon associations (which get processed through the

    multiplexer's MID configuration to get distributed to all the associated

    samples).  This command is performed automatically as a consequence of the

    more specific command above that also specifies an amplicon.

    assoc[iate] -mul[tiplexer] <multiplexer name>

                [-primer1Mid <primer1Mid name>

                    [-ofPrimer1MidGroup <primer1MidGroup name>]]

                [-primer2Mid <primer2Mid name>

                    [-ofPrimer2MidGroup <primer2MidGroup name>]]

                -checkMid <boolean>

                -sam[ple] <sample name>

                -amp[licon] <amplicon name> [-ofRef <reference sequence name>]

                -readData <read data name> | -readGroup <read group name>

                [-file <file> [-format <format>]]

    It is also possible to specify all of the entities in a relationship at

    once.  Provided that all of the individual entities have already been

    created, this command creates a specific read data-multiplexer-amplicon

    context where the multiplexer has an MID configuration that allows valid

    mapping to samples.  This allows the AVA software to analyze reads at the

    amplicon level and properly demultiplex them to their appropriate samples.

    All of the necessary implied relationships in the command would be created

    automatically.  A string of commands of this type might be used to define

    the associations for an entire project.  This would not be a good strategy

    when typing in commands by hand, but it could be convenient for setup

    scripts that are programmatically generated using nested loops and tabular

    commands.