Generic Function Run-Pipeline (4 methods)

( run-pipeline < input > < output > &key &allow-other-keys )

Part of:

package elprep
Reads a SAM data set from input, applies filters to the header and the alignments,
and writes the result to output. Eventually returns the output.

Uses *number-of-threads* to execute the pipeline in parallel. (Default: 1.)

Accepted keywords:
- :filters: A list of filters. Default is the empty list.
- :destructive: Operate destructively on the input or not. One of :default (the default), false, or true.
- :sorting-order: One of :keep (the default), :unsorted, :unkown, :coordinate, or :queryname.
- :chunk-size: Number of alignments to read from input at a time. Default is +default-chunk-size+.
- :header: A header to use in place of the header found in input.
- :split-file: Operate on intermediate split files or not. One of false (the default), or true.

A filter is a function that accepts zero or more arguments and returns zero or more values:
- The first return value is nil or a next-level filter.
- The second value is nil or a thunk to initialize filtering at the next level.
- The third value is nil or a thunk to finalize filtering at the next level.

The levels are: global, then thread-local, then local.

For operating on SAM data sets:
- A global filter receives the SAM header that it can modify.
If an alignment filter is needed, the global filter needs to return a thread-local filter.
- The thread-local filter receives no arguments.
If an alignment filters is needed, the thread filter needs to return one.
- The local filter finally receives an alignment that it can modify, and returns a boolean value,
indicating whether the alignment is to be included in the final result or not.

run-pipeline can be destructive to the input.
This is indicated by the user with the :destructive keyword parameter that can have on of three values:
- t: Operation is destructive.
- nil: Operation is non-destructive. This may require copying of the input alignments
but this only happens if there are any alignment-filters that may actually modify the alignments.
- :default: Operation is destructive or non-destructive depending on what makes most sense for the given input:
- For in-memory, :default means destructive.
- For files, :default means non-destructive.
- For databases:, :default means non-destructive.

Specialize this generic function for new kinds of input sources.
It is recommended to define two methods: One where only input is specialized, and another one where output
is specialized as well for the same kind of input source, to take advantage of knowing the best way to run
pipelines over the same input and output sources, and to identify cases where the pipeline has to effectively
run in situ because input and output are the same.

Method Summary

run-pipeline < pathname > < pathname > 
run-pipeline < pathname > < t > 
run-pipeline < sam > < sam
run-pipeline < sam > < t >