This class provides a convenient way to iterate over several alignments, and process each alignment entry systematically.

This class is designed such that client program can extend it and customize its behavior. The following snippet illustrates how to do this. See the javadoc for details about each method.

36	            IterateAlignments iterator = new IterateAlignments() {
37	                @Override
38	                public void processAlignmentEntry(AlignmentReader alignmentReader, Alignments.AlignmentEntry alignmentEntry) {
39	                    System.out.printf("query-index: %d target-index: %d target-identifier: %s score: %f %n",
40	                            alignmentEntry.getQueryIndex(),
41	                            alignmentEntry.getTargetIndex(),
42	                            getReferenceId(alignmentEntry.getTargetIndex()),
43	                            alignmentEntry.getScore());
44	                }
45	            };
46	            String basenames[] = {"input1.entries", "input2.entries"};
48	            iterator.parseIncludeReferenceArgument("1,2,X");
50	            iterator.iterate(basenames);

Line 36 creates an instance of a sub-class of IterateAlignments. The sub-class is dynamically declared to override the processAlignmentEntry method (lines 37-44). This method will be called for each alignment entry provided to the iterator.

On line 46, the set of alignment basenames to process is defined.

On line 48, the iterator is provided with a list of reference sequence identifiers that should be processed. Entries that match other reference sequences will not be processed. If line 48 was omitted, every alignment entry contained in input1 and input2 would be processed.

On line 50, the iterator is asked to process the alignments in the basenames array. This will result in a call to the processAlignmentEntry for each entry whose reference sequence is on chromosome 1,2 or X.

On line 42, the reference sequence identifier is retrieved for each target index from the iterator. The method getReferenceId is provided by the iterator as a service. Information mapping targetIndex to target identifier is provided in the alignment header (this file is be read by IterateAlignment for each alignment processed). Since target identifiers are optional in alignment headers, line 42 should test that the result of getReferenceId is not null. This test is omitted from this short snippet.

When used this way, IterateAlignment will use each alignment index if it is available (if the alignment was sorted and if a file ‘basename’.index can be loaded). When an index is available, only the parts of the alignment that contain entries matching references 1,2 or X need to be loaded and parsed. This speeds processing considerably for very large files when only a subset of genomic locations need to be processed.