Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## de.jstacs.data
Class Sample

    java.lang.Object
      de.jstacs.data.Sample

    public class Sample

extends Object

This is the class for any sample of sequences. All sequences in a sample have to have the same AlphabetContainer. The sequences may have different lengths.
For the internal representation the class Sequence is used, where the external alphabet is converted to integral numerical values. The class Sample knows about this coding via instances of class AlphabetContainer respectively Alphabet.
There are different ways to access the elements of a Sample. If one needs random access there's the method getElementAt( int i ). For fast sequential access it is recommended to use an ElementEnumerator.
Sample is immutable.

Author:
  Jens Keilwagen
See Also:
  `AlphabetContainer`, `Sequence`

Nested Class Summary
`static class` | `Sample.ElementEnumerator` This class can be used to have a fast sequential access to a sample.
`static class` | `Sample.PartitionMethod` This enum defines different partition method for a sample.
`static class` | `Sample.WeightedSampleFactory` This class enables you to eliminate sequences that occur more than once in one or more samples.

Constructor Summary
`Sample(AlphabetContainer abc, StringExtractor se)` Creates a Sample from a StringExctractor using the given AlphabetContainer.
`Sample(AlphabetContainer abc, StringExtractor se, int subsequenceLength)` Creates a Sample from a StringExctractor using the given AlphabetContainer and all overlapping windows of `subsequenceLength`.
`Sample(AlphabetContainer abc, StringExtractor se, String delim)` Creates a Sample from a StringExctractor using the given AlphabetContainer and delimiter.
`Sample(AlphabetContainer abc, StringExtractor se, String delim, int subsequenceLength)` Creates a Sample from a StringExctractor using the given AlphabetContainer, the given delimiter and all overlapping windows of `subsequenceLength`.
`Sample(Sample s, int subsequenceLength)` This constructor enables you to use subsequences of the elements of a sample.
`Sample(String annotation, Sequence... seqs)` This constructor is specially designed for the method `Model.emitSample(int, int...)`.

Method Summary
`Sequence[]` | `getAllElements()` Returns an array of sequences containing all elements of this Sample.
`AlphabetContainer` | `getAlphabetContainer()` Returns the AlphabetContainer of this Sample.
`String` | `getAnnotation()` This method returns some annotation of the sample.
`static String` | `getAnnotation(Sample... s)` Returns the annotation for an array of Samples
`Sample` | `getCompositeSample(int[] starts, int[] lengths)` This method enables you to use only an composite sequences of all elements in the current sample.
`Sequence` | `getElementAt(int i)` This method returns the element with index `i`.
`int` | `getElementLength()` Returns the length of the elements in this Sample.
`Sample` | `getInfixSample(int start, int length)` This method enables you to use only an infix of all elements in the current sample.
`int` | `getMaximalElementLength()` Returns the maximal length of an element in this Sample.
`int` | `getMinimalElementLength()` Returns the minimal length of an element in this Sample.
`int` | `getNumberOfElements()` Returns the number of elements in this Sample.
`int` | `getNumberOfElementsWithLength(int len)` Returns the number of overlapping elements that can be extracted.
`Sample` | `getSuffixSample(int start)` This method enables you to use only an suffix of all elements in the current sample.
`static Sample` | `intersection(Sample... samples)` This method computes the intersection between all elements of the array, i.e.
`boolean` | `isDiscreteSample()` This method returns `true` all positions use discrete values.
`boolean` | `isSimpleSample()` This method answers the question whether all random variable are defined over the same range, i.e. all positions use the same (fixed) alphabet.
`Sample[]` | `partition(double p, Sample.PartitionMethod method, int subsequenceLength)` This method partitions the elements of the sample in `2` distinct parts.
`Sample[]` | `partition(int k, Sample.PartitionMethod method)` This method partitions the elements of the sample in `k` distinct parts.
`Sample[]` | `partition(Sample.PartitionMethod method, double... percentage)` This method partitions the elements of the sample in distinct parts.
`void` | `save(String msg, File f)` This method writes a message `msg` and the sample to a file `f```
`Sample` | `subSampling(int number)` Randomly samples elements (sequences) from the set of all elements (sequences) contained in this `Sample`.
`String` | `toString()`
`static Sample` | `union(Sample... s)` Unites all samples in `s`
`static Sample` | `union(Sample[] s, boolean[] in)` This method unites all Sample from `s` regarding `in`.
`static Sample` | `union(Sample[] s, boolean[] in, int subsequenceLength)` This method unites all Sample from `s` regarding `in` and sets the element length in the united sample to `subsequenceLength`.
`static Sample` | `union(Sample[] s, int subsequenceLength)` This method unites all Sample from `s` and sets the element length in the united sample to `subsequenceLength`.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

Constructor Detail

### Sample

    public Sample(AlphabetContainer abc,
                  StringExtractor se)
           throws WrongAlphabetException,
                  EmptySampleException,
                  WrongLengthException

  Creates a Sample from a StringExctractor using the given AlphabetContainer.

  Parameters:
    `abc` - the AlphabetContainer
    `se` - the StringExtractor
  Throws:
    `WrongAlphabetException` - if the AlphabetContainer is not suitable
    `EmptySampleException` - if the Sample would be empty
    `WrongLengthException` - never happens

### Sample

    public Sample(AlphabetContainer abc,
                  StringExtractor se,
                  int subsequenceLength)
           throws WrongAlphabetException,
                  WrongLengthException,
                  EmptySampleException

  Creates a Sample from a StringExctractor using the given AlphabetContainer and all overlapping windows of `subsequenceLength`.

  Parameters:
    `abc` - the AlphabetContainer
    `se` - the StringExtractor
    `subsequenceLength` - the length of the window, sliding of the String of `se`. If `len` is 0 (zero) than the sequences are used as given from the StringExtractor.
  Throws:
    `WrongAlphabetException` - if the AlphabetContainer is not suitable
    `WrongLengthException` - if the subsequence length is not supported
    `EmptySampleException` - if the Sample would be empty

### Sample

    public Sample(AlphabetContainer abc,
                  StringExtractor se,
                  String delim)
           throws WrongAlphabetException,
                  EmptySampleException,
                  WrongLengthException

  Creates a Sample from a StringExctractor using the given AlphabetContainer and delimiter.

  Parameters:
    `abc` - the AlphabetContainer
    `se` - the StringExtractor
    `delim` - the delimiter for parsing the Strings
  Throws:
    `WrongAlphabetException` - if the AlphabetContainer is not suitable
    `EmptySampleException` - if the Sample would be empty
    `WrongLengthException` - never happens

### Sample

    public Sample(AlphabetContainer abc,
                  StringExtractor se,
                  String delim,
                  int subsequenceLength)
           throws EmptySampleException,
                  WrongAlphabetException,
                  WrongLengthException

  Creates a Sample from a StringExctractor using the given AlphabetContainer, the given delimiter and all overlapping windows of `subsequenceLength`.

  Parameters:
    `abc` - the AlphabetContainer
    `se` - the StringExtractor
    `delim` - the delimiter for parsing the Strings
    `subsequenceLength` - the length of the window, sliding of the String of `se`. If `len` is 0 (zero) than the sequences are used as given from the StringExtractor.
  Throws:
    `WrongAlphabetException` - if the AlphabetContainer is not suitable
    `EmptySampleException` - if the Sample would be empty
    `WrongLengthException` - if the subsequence length is not supported

### Sample

    public Sample(Sample s,
                  int subsequenceLength)
           throws WrongLengthException

  This constructor enables you to use subsequences of the elements of a sample.
  It can also be used to ensure that all sequences that can be accessed by `getElementAt( int i )` are real objects and do not have to be created at the invocation of the method. (The same holds for the ElementEnumerator. In those cases both ways to access the sequence are approximately equally fast.)

  Parameters:
    `s` - the sample
    `subsequenceLength` - the new element length
  Throws:
    `WrongLengthException` - if something is wrong with subsequenceLength

### Sample

    public Sample(String annotation,
                  Sequence... seqs)
           throws EmptySampleException,
                  IllegalArgumentException

  This constructor is specially designed for the method `Model.emitSample(int, int...)`.

  Parameters:
    `annotation` - the annotation of the sample
    `seqs` - the sequence(s)
  Throws:
    `EmptySampleException` - if the array `seqs` is `null` or the length is 0
    `IllegalArgumentException` - if the alphabets do not match

Method Detail

### getAnnotation

    public static final String getAnnotation(Sample... s)

  Returns the annotation for an array of Samples

  Parameters:
    `s` - an array of Samples
  Returns:
    the annotation

### intersection

    public static final Sample intersection(Sample... samples)
                                     throws IllegalArgumentException,
                                            EmptySampleException

  This method computes the intersection between all elements of the array, i.e. it returns a Sample containing only sequences that are contained in all Samples of the array.

  Parameters:
    `samples` - the array
  Returns:
    the intersection of the elements in the array
  Throws:
    `IllegalArgumentException` - if the elements of the array are from different domains
    `EmptySampleException` - if the intersection is empty

### union

    public static final Sample union(Sample[] s,
                                     boolean[] in)
                              throws IllegalArgumentException,
                                     EmptySampleException

  This method unites all Sample from `s` regarding `in`.

  Parameters:
    `s` - the Samples
    `in` - an array indicating which sample is used in the union, if `in[i]==true` the sample `s[i]` is used.
  Returns:
    the united sample
  Throws:
    `IllegalArgumentException` - if s.length != in.length or the alphabets do not match
    `EmptySampleException` - if the union is empty

### union

    public static final Sample union(Sample... s)
                              throws IllegalArgumentException

  Unites all samples in `s`

  Parameters:
    `s` - the samples
  Returns:
    the united sample
  Throws:
    `IllegalArgumentException` - if the alphabets do not match
  See Also:
    `union(Sample[], boolean[])`

### union

    public static final Sample union(Sample[] s,
                                     boolean[] in,
                                     int subsequenceLength)
                              throws IllegalArgumentException,
                                     EmptySampleException,
                                     WrongLengthException

  This method unites all Sample from `s` regarding `in` and sets the element length in the united sample to `subsequenceLength`.

  Parameters:
    `s` - the Samples
    `in` - an array indicating which sample is used in the union, if `in[i]==true` the sample `s[i]` is used.
    `subsequenceLength` - the length of the elements in the united sample
  Returns:
    the united sample
  Throws:
    `IllegalArgumentException` - if s.length != in.length or the alphabets do not match
    `EmptySampleException` - if the union is empty
    `WrongLengthException` - if the united sample does not support this subsequenceLength

### union

    public static final Sample union(Sample[] s,
                                     int subsequenceLength)
                              throws IllegalArgumentException,
                                     WrongLengthException

  This method unites all Sample from `s` and sets the element length in the united sample to `subsequenceLength`.

  Parameters:
    `s` - the Samples
    `subsequenceLength` - the length of the elements in the united sample
  Returns:
    the united sample
  Throws:
    `IllegalArgumentException` - if the alphabets do not match
    `WrongLengthException` - if the united sample does not support this subsequenceLength
  See Also:
    `union(Sample[], boolean[], int)`

### getAllElements

    public Sequence[] getAllElements()

  Returns an array of sequences containing all elements of this Sample.

  Returns:
    all elements (sequences) of this Sample

### getAlphabetContainer

    public final AlphabetContainer getAlphabetContainer()

  Returns the AlphabetContainer of this Sample.

  Returns:
    the AlphabetContainer of this Sample

### getAnnotation

    public final String getAnnotation()

  This method returns some annotation of the sample.

  Returns:
    some annotation of the sample

### getCompositeSample

    public final Sample getCompositeSample(int[] starts,
                                           int[] lengths)
                                    throws IllegalArgumentException

  This method enables you to use only an composite sequences of all elements in the current sample. The composite sequences will be returned in an new sample.

  Parameters:
    `starts` - the start positions
    `lengths` - the lengths of the chunks
  Returns:
    a composite sample
  Throws:
    `IllegalArgumentException` - if either start or length or both in combination are not suitable

### getElementAt

    public Sequence getElementAt(int i)

  This method returns the element with index `i`. See also this comment.

  Parameters:
    `i` - the index
  Returns:
    the element

### getElementLength

    public int getElementLength()

  Returns the length of the elements in this Sample.

  Returns:
    the length of the elements in this Sample

### getInfixSample

    public final Sample getInfixSample(int start,
                                       int length)
                                throws IllegalArgumentException

  This method enables you to use only an infix of all elements in the current sample. The subsequences will be returned in an new sample.
  This method can also be used to create a sample of prefixes if the element length is not zero.

  Parameters:
    `start` - the start position of the infix
    `length` - the length of the infix, has to be positive
  Returns:
    a sample of specified infixe
  Throws:
    `IllegalArgumentException` - if either start or length or both in combination are not suitable

### getMinimalElementLength

    public int getMinimalElementLength()

  Returns the minimal length of an element in this Sample.

  Returns:
    the minimal length of an element in this Sample

### getMaximalElementLength

    public int getMaximalElementLength()

  Returns the maximal length of an element in this Sample.

  Returns:
    the maximal length of an element in this Sample

### getNumberOfElements

    public int getNumberOfElements()

  Returns the number of elements in this Sample.

  Returns:
    the number of elements in this Sample

### getNumberOfElementsWithLength

    public int getNumberOfElementsWithLength(int len)
                                      throws WrongLengthException

  Returns the number of overlapping elements that can be extracted.

  Parameters:
    `len` - the length of the elements
  Returns:
    the number of elements with the specified length
  Throws:
    `WrongLengthException` - if the given length is bigger than the minimal element length

### getSuffixSample

    public final Sample getSuffixSample(int start)
                                 throws IllegalArgumentException

  This method enables you to use only an suffix of all elements in the current sample. The subsequences will be returned in an new sample.

  Parameters:
    `start` - the start position of the suffix
  Returns:
    a sample of specified suffixes
  Throws:
    `IllegalArgumentException` - if either start is not suitable

### isSimpleSample

    public final boolean isSimpleSample()

  This method answers the question whether all random variable are defined over the same range, i.e. all positions use the same (fixed) alphabet.

  Returns:
    `true` if the sample is simple

### isDiscreteSample

    public final boolean isDiscreteSample()

  This method returns `true` all positions use discrete values.

  Returns:
    `true` if the sample is discrete

### partition

    public Sample[] partition(double p,
                              Sample.PartitionMethod method,
                              int subsequenceLength)
                       throws WrongLengthException,
                              UnsupportedOperationException,
                              EmptySampleException

  This method partitions the elements of the sample in `2` distinct parts. The second part (test sample) holds the percentage of `p`, the first the rest (train sample). The first part has element length as the current sample, the second has element length `subsequenceLength`.

  Parameters:
    `p` - the percentage for the second part, the second part holds at least this percentage of the full sample
    `method` - the method how to partition the sample (partitioning criterion)
    `subsequenceLength` - the element length of the second part. If `len` is 0 (zero) than the sequences are used as given in this Sample.
  Returns:
    the partitioned sample
  Throws:
    `WrongLengthException` - if some is wrong with `subsequenceLength`
    `UnsupportedOperationException` - if the sample is not simple
    `EmptySampleException` - if at least one of the created partitions is empty
  See Also:
    `Sample.PartitionMethod.PARTITION_BY_NUMBER_OF_ELEMENTS`, `Sample.PartitionMethod.PARTITION_BY_NUMBER_OF_SYMBOLS`

### partition

    public Sample[] partition(Sample.PartitionMethod method,
                              double... percentage)
                       throws IllegalArgumentException,
                              EmptySampleException

  This method partitions the elements of the sample in distinct parts.

  Parameters:
    `method` - the method how to partition the sample (partitioning criterion)
    `percentage` - the array of percentage for each "subsample"
  Returns:
    the array of "subsamples"
  Throws:
    `IllegalArgumentException` - if something with the percentages is not correct (sum != 1 or one value not in [0,1])
    `EmptySampleException` - if at least one of the created partitions is empty
  See Also:
    `Sample.PartitionMethod.PARTITION_BY_NUMBER_OF_ELEMENTS`, `Sample.PartitionMethod.PARTITION_BY_NUMBER_OF_SYMBOLS`

### partition

    public Sample[] partition(int k,
                              Sample.PartitionMethod method)
                       throws IllegalArgumentException,
                              EmptySampleException

  This method partitions the elements of the sample in `k` distinct parts.

  Parameters:
    `k` - the number of parts
    `method` - how to split the data
  Returns:
    the array of "subsamples"
  Throws:
    `IllegalArgumentException` - if `k` is not correct
    `EmptySampleException` - if at least one of the created partitions is empty
  See Also:
    `Sample.PartitionMethod.PARTITION_BY_NUMBER_OF_ELEMENTS`, `Sample.PartitionMethod.PARTITION_BY_NUMBER_OF_SYMBOLS`

### subSampling

    public Sample subSampling(int number)
                       throws EmptySampleException

  Randomly samples elements (sequences) from the set of all elements (sequences) contained in this `Sample`.
  Depending on whether this Sample is chosen to contain overlapping elements (windows of length subsequenceLength) or not, those elements (overlapping windows, whole sequences) are subsampled.

  Parameters:
    `number` - of Sequences that should be drawn from the contained set of sequences (with replacement)
  Returns:
    a new Sample containing the drawn Sequences
  Throws:
    `EmptySampleException` - if number is not positive

### save

    public final void save(String msg,
                           File f)
                    throws IOException

  This method writes a message `msg` and the sample to a file `f`

  ``
  Parameters:
    `msg` - the message, any information
    `f` - the File
  Throws:
    `IOException` - if something went wrong with the file

### toString

    public String toString()

  Overrides:
    `toString` in class `Object`

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD