Package picard.metrics

## Class MultiLevelCollector<METRIC_TYPE extends htsjdk.samtools.metrics.MetricBase,​Histogram_KEY extends Comparable,​ARGTYPE>

- java.lang.Object
- - picard.metrics.MultiLevelCollector<METRIC_TYPE,​Histogram_KEY,​ARGTYPE>

- Type Parameters:
    `METRIC_TYPE` - The type of metrics being collected
    `Histogram_KEY` - If there is are Histograms related to metrics of type <BEAN> then <HKEY> is the key value to these Histograms
    `ARGTYPE` - The type of argument passed to individual PerUnitMetricCollector (see SAMRecordMultilevelCollector and PerUnitMetricCollector)
  Direct Known Subclasses:
    `GcBiasMetricsCollector`, `InsertSizeMetricsCollector`, `SAMRecordAndReferenceMultiLevelCollector`, `SAMRecordMultiLevelCollector`

      public abstract class MultiLevelCollector<METRIC_TYPE extends htsjdk.samtools.metrics.MetricBase,​Histogram_KEY extends Comparable,​ARGTYPE>
      extends Object

  MultiLevelCollector handles accumulating Metrics at different MetricAccumulationLevels(ALL_READS, SAMPLE, LIBRARY, READ_GROUP). Based on the accumulationLevels and readGroup records passed to its constructor, MultiLevelCollector will instantiate the number of PerUnitMetricCollector's needed to generate metrics for each of the levels provided. To Use: Instantiate a MultiLevelCollector and call setup(see thoughts about extending MultiLevelCollector below) setup will create the underlying classes that will handle the accumulation level logic. Pass all reads you wish to collect data against to MultiLevelCollector via the acceptRecord method Call finish and use addAllLevelsToFile to add all of the metrics at each accumulation level to the given file. Extend MultiLevelCollector and implement makeArg and makeChildCollector You will most likely want to make a class that extends PerUnitMetricCollector. This class should do the work of keeping track of values for one specific "accumulation unit" (e.g. for one library, or for one read group depending on what levels you are accumulating at). If a record has any expensive calculations to be done (that don't need to be done differently depending on what sample/library/read group the read is for) then create a container class for the results of these calculations and pass this class as the ARGTYPE of both the PerUnitMetricCollector and MultiLevelCollector. You can then do these calculations in the makeArg method and they will only be done once per record.

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static String` | `UNKNOWN` |

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `MultiLevelCollector()` |

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `acceptRecord​(htsjdk.samtools.SAMRecord record, htsjdk.samtools.reference.ReferenceSequence refSeq)` | Construct a argument of ARGTYPE using the given SAMRecord and ReferenceSequence then pass this value to all collectors that should include this record
    `void` | `addAllLevelsToFile​(htsjdk.samtools.metrics.MetricsFile<METRIC_TYPE,​Histogram_KEY> file)` | Add all metrics to the given file in the following MetricAccumulationLevel order ALL_READS, SAMPLE, LIBRARY, READ_GROUP.
    `void` | `finish()` | Call finish on all PerUnitMetricCollectors
    `PerUnitMetricCollector<METRIC_TYPE,​Histogram_KEY,​ARGTYPE>` | `getAllReadsCollector()` | Get the PerUnitMetricCollector that collects reads for all levels
    `protected PerUnitMetricCollector<METRIC_TYPE,​Histogram_KEY,​ARGTYPE>` | `makeAllReadCollector()` |
    `protected abstract ARGTYPE` | `makeArg​(htsjdk.samtools.SAMRecord samRec, htsjdk.samtools.reference.ReferenceSequence refSeq)` |
    `protected abstract PerUnitMetricCollector<METRIC_TYPE,​Histogram_KEY,​ARGTYPE>` | `makeChildCollector​(String sample, String library, String readGroup)` | Construct a PerUnitMetricCollector with the given arguments.
    `protected PerUnitMetricCollector<METRIC_TYPE,​Histogram_KEY,​ARGTYPE>` | `makeLibraryCollector​(htsjdk.samtools.SAMReadGroupRecord rg)` |
    `protected PerUnitMetricCollector<METRIC_TYPE,​Histogram_KEY,​ARGTYPE>` | `makeReadGroupCollector​(htsjdk.samtools.SAMReadGroupRecord rg)` |
    `protected PerUnitMetricCollector<METRIC_TYPE,​Histogram_KEY,​ARGTYPE>` | `makeSampleCollector​(htsjdk.samtools.SAMReadGroupRecord rg)` |
    `protected void` | `setup​(Set<MetricAccumulationLevel> accumulationLevels, List<htsjdk.samtools.SAMReadGroupRecord> samRgRecords)` | Use an init method so that overloaded methods in subclasses can pass use parameters that are initialized in their constructor

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### UNKNOWN

          public static final String UNKNOWN

      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### MultiLevelCollector

          public MultiLevelCollector()

  - ### Method Detail

    - #### makeArg

          protected abstract ARGTYPE makeArg​(htsjdk.samtools.SAMRecord samRec,
                                             htsjdk.samtools.reference.ReferenceSequence refSeq)

    - #### makeChildCollector

          protected abstract PerUnitMetricCollector<METRIC_TYPE,​Histogram_KEY,​ARGTYPE> makeChildCollector​(String sample,
                                                                                                                      String library,
                                                                                                                      String readGroup)

      Construct a PerUnitMetricCollector with the given arguments.
      Parameters:
        `sample` - If aggregating by ALL_READS this will be null, otherwise the sample that will be used to identify this collector
        `library` - If aggregating by SAMPLE this will be null, otherwise the library that will be used to identify this collector
        `readGroup` - If aggregating by LIBRARY this will be null, otherwise the readGroup that will be used to identify this collector
      Returns:
        A PerUnitMetricCollector parameterized by the given arguments

    - #### makeAllReadCollector

          protected PerUnitMetricCollector<METRIC_TYPE,​Histogram_KEY,​ARGTYPE> makeAllReadCollector()

    - #### makeSampleCollector

          protected PerUnitMetricCollector<METRIC_TYPE,​Histogram_KEY,​ARGTYPE> makeSampleCollector​(htsjdk.samtools.SAMReadGroupRecord rg)

    - #### makeLibraryCollector

          protected PerUnitMetricCollector<METRIC_TYPE,​Histogram_KEY,​ARGTYPE> makeLibraryCollector​(htsjdk.samtools.SAMReadGroupRecord rg)

    - #### makeReadGroupCollector

          protected PerUnitMetricCollector<METRIC_TYPE,​Histogram_KEY,​ARGTYPE> makeReadGroupCollector​(htsjdk.samtools.SAMReadGroupRecord rg)

    - #### setup

          protected void setup​(Set<MetricAccumulationLevel> accumulationLevels,
                               List<htsjdk.samtools.SAMReadGroupRecord> samRgRecords)

      Use an init method so that overloaded methods in subclasses can pass use parameters that are initialized in their constructor
      Parameters:
        `accumulationLevels` - PerUnitMetricCollectors will only be created for the levels identified by accumulationLevels
        `samRgRecords` - PerUnitMetricCollectors will be created for each of the different samples, libraries, and readGroups found in the records depending on the accumulationLevels provided

    - #### acceptRecord

          public void acceptRecord​(htsjdk.samtools.SAMRecord record,
                                   htsjdk.samtools.reference.ReferenceSequence refSeq)

      Construct a argument of ARGTYPE using the given SAMRecord and ReferenceSequence then pass this value to all collectors that should include this record

    - #### finish

          public void finish()

      Call finish on all PerUnitMetricCollectors

    - #### getAllReadsCollector

          public PerUnitMetricCollector<METRIC_TYPE,​Histogram_KEY,​ARGTYPE> getAllReadsCollector()

      Get the PerUnitMetricCollector that collects reads for all levels

    - #### addAllLevelsToFile

          public void addAllLevelsToFile​(htsjdk.samtools.metrics.MetricsFile<METRIC_TYPE,​Histogram_KEY> file)

      Add all metrics to the given file in the following MetricAccumulationLevel order ALL_READS, SAMPLE, LIBRARY, READ_GROUP.