    001    package calhoun.analysis.crf.io;
    002
    003    import java.io.IOException;
    004    import java.io.Serializable;
    005    import java.util.List;
    006    import java.util.Map;
    007
    008    /** interface to read or write {@link InputSequence} components to or from a file.  A single <code>InputComponentIO</code> is responsible for
    009     * reading and writing data at a single location, but may work with multiple components of the input sequence.
    010     */
    011    public interface InputComponentIO extends Serializable {
    012
    013            /** A list of names of the components of the InputSequence created by this reader.
    014             * @return a list of input sequence component names. */
    015            List<String> getComponentNames();
    016
    017            /** reads input sequences from this location.  In most cases the location will be a file and this object will read in one or more components of the
    018             * overall input from that file.  Alist of inputs is returned.  Each input consists of a set of key-value pairs, where the key is the name of the
    019             * input component and the value is an (@link InputSequence) object.  If this is not the first component to be loaded, this list may already contain
    020             * entries for the input.
    021             * @param location the location of the data to read.  Meaning of the location is implementation dependent, but will usually be a file name.
    022             * @param inputs a list of input sequences.  For each input sequence, a map is returned that maps component names to their
    023             * associated {@link InputSequence} objects.
    024             */
    025            void readInputSequences(String location, List<Map<String, InputSequence<?>>> inputs) throws IOException;
    026
    027            /** writes input sequences to this location.  <code>InputComponentIO</code> optionally can implement this function to provide the ability to write input
    028             * data as well as read it.  This is used by many of the data manipulation tools, such as those for subsetting and creating cross-validation sets.
    029             * @param location the location of the data to write.  Meaning of the location is implementation dependent, but will usually be a file name.
    030             * @param inputComponents an iterator over input sequences.  For each input sequence, a map is returned that maps component names to their
    031             * associated {@link InputSequence} objects.  All components of the input are passed, and this object is reponsible for knowing which components
    032             * it should be writing.
    033             */
    034            void writeInputSequences(String location, List<? extends Map<String, ? extends InputSequence<?>>> inputComponents)  throws IOException;
    035    }