de.jstacs.data
Class Sample

java.lang.Object
  extended by 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