Package org.broadinstitute.hellbender.utils.tsv

Class TableWriter<R>

java.lang.Object
org.broadinstitute.hellbender.utils.tsv.TableWriter<R>
Type Parameters:
R - the row record type.
All Implemented Interfaces:
Closeable, AutoCloseable
Direct Known Subclasses:
AltSiteRecord.AltSiteRecordTableWriter, ArtifactPrior.ArtifactPriorTableWriter, CheckReferenceCompatibility.CheckReferenceCompatibilityTableWriter, CompareReferences.CompareReferencesOutputTableWriter, CompareReferences.FindSNPsOnlyTableWriter, ConcordanceSummaryRecord.Writer, GeneExpressionEvaluation.FragmentCountWriter, InfoConcordanceRecord.InfoConcordanceWriter, NormalArtifactRecord.NormalArtifactWriter, PileupSummary.PileupSummaryTableWriter
public abstract class TableWriter<R> extends Object implements Closeable
Class to write tab separated value files.

The column (and they names) are passed in the constructor parameter along the output path or writer.

Extending classes must indicate how we can transcribe row record or type TableWriter to the corresponding record data-line in the output by overriding composeLine(R,DataLine).

Example: 

         public class Person {
             public final String name;
             public final int age;
             public final double netWorth;
         }

         public class PeopleTableWriter extends TableWriter<Person> {

             public MyRecordWriter(final File file) {
                 super(file, new TableColumnCollection("name","age","net.worth"));
             }

             @Override
             protected void dataLine(final Person person, final DataLine dataLine) {
                  dataLine.setAll(person.name, "" + person.age, "" + person.netWorth);
             }
         }

You must use the DataLine instance passed and no other.

Instead of passing all the values as converted string in column order you may opt to use DataLine.set(java.lang.String, java.lang.String) method family to set values one by one using the column index or column name like so:

Example (using the column index): 

          @Override
          protected void composeLine(final Person person, final DataLine dataLine) {
              dataLine
                  .set(0,person.name)
                  .set(1,person.age)
                  .set(2,person.netWorth);
          }

Example (using column names): 

          @Override
          protected void composeLine(final Person person, final DataLine dataLine) {
              dataLine
                  .set("name",person.name)
                  .set("age",person.age)
                  .set("net.worth",person.netWorth);
          }
Notice that you don't need to explicitly convert neither the age nor the net-worth into a string thanks to set various overloads.

Alternatively, if you know the column order, that should quite often the case, you can avoid indexing all together using append operations instead: 

         @Override
          protected void composeLine(final Person person, final DataLine dataLine) {
              dataLine
                  .append(person.name)
                  .append(person.age)
                  .append(person.netWorth);
          }

At any time the implementation can query the correspondence between column names and position within the data-line by querying the TableColumnCollection object directly that can be obtained from the dataLine's columns field.

Example (using column names): 

          @Override
          protected void composeLine(final Person person, final DataLine dataLine) {
              dataLine
                .set("name",person.name)
                .set("age",person.age);

              if (dataLine.columns().contains("net.worth"))
                dataLine.set("net.worth",person.netWorth);
          }

  • Field Details

  • Constructor Details

    • TableWriter

      public TableWriter(Path path, TableColumnCollection tableColumns) throws IOException
      Creates a new table writer given the file and column names.
      Parameters:
      path - the destination path.
      tableColumns - the table column names.
      Throws:
      IllegalArgumentException - if either file or tableColumns are null.
      IOException - if one was raised when opening the the destination file for writing.

    • TableWriter

      public TableWriter(Writer writer, TableColumnCollection columns) throws IOException
      Creates a new table writer given the destination writer and column names.
      Parameters:
      writer - the destination writer.
      columns - the table column names.
      Throws:
      IllegalArgumentException - if either writer or columns are null.
      IOException - if one was raised when opening the the destination file for writing.

  • Method Details

    • writeComment

      public final void writeComment(String comment) throws IOException
      Writes a comment into the output.

      This can be invoked at any time; comment lines can be present anywhere in the file.

      Comments written before any record, will be output

      Parameters:
      comment - the comment to write out.
      Throws:
      IllegalArgumentException - if comment is null.
      IOException - if any was raised by this operation.

    • writeMetadata

      public final void writeMetadata(String key, String value) throws IOException
      Throws:
      IOException

    • writeRecord

      public void writeRecord(R record) throws IOException
      Writes a new record.
      Parameters:
      record - the record to write.
      Throws:
      IOException - if it was raised when writing the record.
      ClassCastException - if record is of the correct type for this writer.
      IllegalArgumentException - if record is null or it is not a valid record as per the implementation of this writer (see composeLine(R, org.broadinstitute.hellbender.utils.tsv.DataLine)).

    • writeAllRecords

      public final void writeAllRecords(Iterable<R> records) throws IOException
      Write all the records in a Iterable.

      Records are written in the order they appear in the input Iterable.

      Parameters:
      records - to write.
      Throws:
      IOException - if any raised when writing any of the records.
      ClassCastException - if record is of the correct type for this writer.
      IllegalArgumentException - if records is null or it contains some values that would cause such an exception when writeRecord(R) is call on that value. Previous record in the iterable would have been already written by then.

    • close

      public final void close() throws IOException
      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface Closeable
      Throws:
      IOException

    • flush

      public final void flush() throws IOException
      Pushes in-memory buffered content to the output stream.
      Throws:
      IOException

    • writeHeaderIfApplies

      public void writeHeaderIfApplies() throws IOException
      Writes the header if it has not been written already.

      The header is written automatically before the first record is written or when the writer is closed and no record was written.

      Comments written using writeComment(java.lang.String) before any record will precede the header unless you invoke your method first.

      Once the header line has been written, invoking this method does not have any effect.

      Throws:
      IOException - if any raised when writing into the destination writer.

    • composeLine

      protected abstract void composeLine(R record, DataLine dataLine)
      Composes the data-line to write into the output to represent a given record

      Also the first element cannot contain the comment prefix. If that is a genuine valid value for the first column you shall consider to re-order the columns or change the encoding of the first column to avoid this issue.

      Both inputs, record and dataLine are guaranteed not to be nulls.

      Parameters:
      record - the record to write into the data-line.
      dataLine - the destination data-line object.
      Throws:
      ClassCastException - if record is of the correct type for this writer.
      IllegalArgumentException - if there is some conversion issue that does not allow the current write to generate a valid string array to encode the record.