natas_hw
/
jidt
mirror of https://github.com/jlizier/jidt
0
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Updating javadoc comments in the code, a. to make them more explicit regarding the transfer entropy calculators, and specifically b. to show that addObservations does not append observation time series.

This commit is contained in:
joseph.lizier 2012-08-08 05:33:13 +00:00
parent 12e6f12147
commit 8129dbee7b
9 changed files with 438 additions and 114 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

76
java/source/infodynamics/measures/continuous/ChannelCalculator.java
View File

@ -2,50 +2,92 @@ package infodynamics.measures.continuous;
/**
* An interface for calculators computing measures from a source to a destination
* for single variables in each.
* for single variables in each (specific examples intended here
* are the mutual information and transfer entropy)
*
*
* @author Joseph Lizier, jlizier at gmail.com
* @author Joseph Lizier, <a href="joseph.lizier at gmail.com">email</a>,
* <a href="http://lizier.me/joseph/">www</a>
*
*/
public interface ChannelCalculator extends ChannelCalculatorCommon {
public void initialise() throws Exception;
/**
* <p>Sets the single set of observations to compute the PDFs from.
* Cannot be called in conjunction with
* {@link #startAddObservations()}/{@link #addObservations(double[], double[])} /
* {@link #finaliseAddObservations()}.</p>
*
* @param source observations for the source variable
* @param destination observations for the destination variable
* @throws Exception
*/
public void setObservations(double source[], double destination[]) throws Exception;
/**
* Add some more observations.
* Note that the arrays source and destination must not be over-written by the user
* until after finaliseAddObservations() has been called.
* <p>Adds a new set of observations to update the PDFs with - is
* intended to be called multiple times.
* Must be called after {@link #startAddObservations()}; call
* {@link #finaliseAddObservations()} once all observations have
* been supplied.</p>
*
* @param source
* @param destination
* <p><b>Important:</b> this does not append these observations to the previously
* supplied observations, but treats them independently - i.e. measurements
* such as the transfer entropy will not join them up to examine k
* consecutive values in time.</p>
*
* <p>Note that the arrays source and destination must not be over-written by the user
* until after finaliseAddObservations() has been called
* (they are not copied by this method necessarily, but the method
* may simply hold a pointer to them).</p>
*
* @param source observations for the source variable
* @param destination observations for the destination variable
* @throws Exception
*/
public void addObservations(double[] source, double[] destination) throws Exception;
/**
* Add some more observations.
* <p>Adds a new set of observations to update the PDFs with - is
* intended to be called multiple times.
* Must be called after {@link #startAddObservations()}; call
* {@link #finaliseAddObservations()} once all observations have
* been supplied.</p>
*
* @param source
* @param destination
* <p><b>Important:</b> this does not append these observations to the previously
* supplied observations, but treats them independently - i.e. measurements
* such as the transfer entropy will not join them up to examine k
* consecutive values in time.</p>
*
* <p>Note that the arrays source and destination must not be over-written by the user
* until after finaliseAddObservations() has been called
* (they are not copied by this method necessarily, but the method
* may simply hold a pointer to them).</p>
*
* @param source observations for the source variable
* @param destination observations for the destination variable
* @param startTime first time index to take observations on
* @param numTimeSteps number of time steps to use
* @throws Exception
*/
public void addObservations(double[] source, double[] destination,
int startTime, int numTimeSteps) throws Exception ;
/**
* Sets the observations to compute the PDFs from.
* Cannot be called in conjunction with start/add/finaliseAddObservations.
* destValid is a time series (with time indices the same as destination)
* indicating whether the destination at that point is valid.
* sourceValid is the same for the source
* <p>Sets the single set of observations to compute the PDFs from.
* Cannot be called in conjunction with
* {@link #startAddObservations()}/{@link #addObservations(double[], double[])} /
* {@link #finaliseAddObservations()}.</p>
*
* @param source observations for the source variable
* @param destination observations for the destination variable
* @param sourceValid
* @param destValid
* @param sourceValid time series (with time indices the same as source)
* indicating whether the source at that point is valid.
* @param destValid time series (with time indices the same as destination)
* indicating whether the destination at that point is valid.
* @throws Exception
*/
public void setObservations(double[] source, double[] destination,
boolean[] sourceValid, boolean[] destValid) throws Exception;

31
java/source/infodynamics/measures/continuous/ChannelCalculatorCommon.java
View File

@ -3,10 +3,16 @@ package infodynamics.measures.continuous;
import infodynamics.utils.EmpiricalMeasurementDistribution;
/**
* An abstract interface for calculators computing measures from a source to a destination.
* <p>An abstract interface for calculators computing measures from a source to a destination.
* </p>
*
* <p>The interface is abstract because further specification is required
* for addObservations or setObservations methods showing whether
* this is a univariate or multivariate measure.</p>
*
*
* @author Joseph Lizier, jlizier at gmail.com
* @author Joseph Lizier, <a href="joseph.lizier at gmail.com">email</a>,
* <a href="http://lizier.me/joseph/">www</a>
*
*/
public abstract interface ChannelCalculatorCommon {
@ -32,8 +38,29 @@ public abstract interface ChannelCalculatorCommon {
*/
public void finaliseAddObservations();
/**
*
* @return the average value of the implemented channel measure,
* computed using all of the previously supplied observation sets.
* @throws Exception
*/
public double computeAverageLocalOfObservations() throws Exception;
/**
* <p>Computes the local values of the implemented channel measure,
* for each valid observation in the previously supplied observations
* (with PDFs computed using all of the previously supplied observation sets).</p>
*
* <p>If disjoint observations were supplied using several
* calls such as {@link ChannelCalculator#addObservations(double[], double[])}
* then the local values for each disjoint observation set will be appended here
* to create a single return array,
* though of course the time series for these disjoint observations were
* not appended in computing the required PDFs).</p>
*
* @return array of local values.
* @throws Exception
*/
public double[] computeLocalOfPreviousObservations() throws Exception;
/**

111
java/source/infodynamics/measures/continuous/ChannelCalculatorMultiVariate.java
View File

@ -2,10 +2,12 @@ package infodynamics.measures.continuous;
/**
* An interface for calculators computing measures from a source to a destination
* for multiple joint variables in each.
* for multiple joint variables in each (specific examples intended here
* are the mutual information and transfer entropy).
*
*
* @author Joseph Lizier, jlizier at gmail.com
* @author Joseph Lizier, <a href="joseph.lizier at gmail.com">email</a>,
* <a href="http://lizier.me/joseph/">www</a>
*
*/
public interface ChannelCalculatorMultiVariate extends ChannelCalculatorCommon {
@ -13,43 +15,110 @@ public interface ChannelCalculatorMultiVariate extends ChannelCalculatorCommon {
/**
* Initialise the calculator
*
* @param sourceDimensions the number of joint variables in the source
* @param destDimensions the number of joint variables in the destination
*/
public void initialise(int sourceDimensions, int destDimensions) throws Exception;
/**
* <p>Sets the single set of observations to compute the PDFs from.
* Cannot be called in conjunction with
* {@link #startAddObservations()}/{@link #addObservations(double[], double[])} /
* {@link #finaliseAddObservations()}.</p>
*
* @param source multivariate observations for the source variable
* (first index is time, second is variable number)
* @param destination multivariate observations for the destination variable
* (first index is time, second is variable number)
* @throws Exception
*/
public void setObservations(double[][] source, double[][] destination) throws Exception;
/**
* <p>Adds a new set of observations to update the PDFs with - is
* intended to be called multiple times.
* Must be called after {@link #startAddObservations()}; call
* {@link #finaliseAddObservations()} once all observations have
* been supplied.</p>
*
* <p><b>Important:</b> this does not append these observations to the previously
* supplied observations, but treats them independently - i.e. measurements
* such as the transfer entropy will not join them up to examine k
* consecutive values in time.</p>
*
* <p>Note that the arrays source and destination must not be over-written by the user
* until after finaliseAddObservations() has been called
* (they are not copied by this method necessarily, but the method
* may simply hold a pointer to them).</p>
*
* @param source multivariate observations for the source variable
* (first index is time, second is variable number)
* @param destination multivariate observations for the destination variable
* (first index is time, second is variable number)
* @throws Exception
*/
public void addObservations(double[][] source, double[][] destination) throws Exception;
/**
* <p>Adds a new set of observations to update the PDFs with - is
* intended to be called multiple times.
* Must be called after {@link #startAddObservations()}; call
* {@link #finaliseAddObservations()} once all observations have
* been supplied.</p>
*
* <p><b>Important:</b> this does not append these observations to the previously
* supplied observations, but treats them independently - i.e. measurements
* such as the transfer entropy will not join them up to examine k
* consecutive values in time.</p>
*
* <p>Note that the arrays source and destination must not be over-written by the user
* until after finaliseAddObservations() has been called
* (they are not copied by this method necessarily, but the method
* may simply hold a pointer to them).</p>
*
* @param source multivariate observations for the source variable
* (first index is time, second is variable number)
* @param destination multivariate observations for the destination variable
* (first index is time, second is variable number)
* @param startTime first time index to take observations on
* @param numTimeSteps number of time steps to use
* @throws Exception
*/
public void addObservations(double[][] source, double[][] destination,
int startTime, int numTimeSteps) throws Exception;
/**
* Sets the observations to compute the PDFs from.
* Cannot be called in conjunction with start/add/finaliseAddObservations.
* destValid is a time series (with time indices the same as destination)
* indicating whether the destination at that point is valid.
* sourceValid is the same for the source
* <p>Sets the single set of observations to compute the PDFs from.
* Cannot be called in conjunction with
* {@link #startAddObservations()}/{@link #addObservations(double[], double[])} /
* {@link #finaliseAddObservations()}.</p>
*
* @param source observations for the source variable
* @param destination observations for the destination variable
* @param sourceValid
* @param destValid
* @param source multivariate observations for the source variable
* (first index is time, second is variable number)
* @param destination multivariate observations for the destination variable
* (first index is time, second is variable number)
* @param sourceValid time series (with time indices the same as source)
* indicating whether the source at that point is valid.
* @param destValid time series (with time indices the same as destination)
* indicating whether the destination at that point is valid.
*/
public void setObservations(double[][] source, double[][] destination,
boolean[] sourceValid, boolean[] destValid) throws Exception;
/**
* Sets the observations to compute the PDFs from.
* Cannot be called in conjunction with start/add/finaliseAddObservations.
* destValid is a time series (with time indices the same as destination)
* indicating whether the destination at that point is valid, with one
* validity supplied for each sub-variable.
* sourceValid is the same for the source
* <p>Sets the single set of observations to compute the PDFs from.
* Cannot be called in conjunction with
* {@link #startAddObservations()}/{@link #addObservations(double[], double[])} /
* {@link #finaliseAddObservations()}.</p>
*
* @param source observations for the source variable
* @param destination observations for the destination variable
* @param sourceValid
* @param destValid
* @param source multivariate observations for the source variable
* (first index is time, second is variable number)
* @param destination multivariate observations for the destination variable
* (first index is time, second is variable number)
* @param sourceValid time series (with time indices the same as source)
* indicating whether each variable of the source at that point is valid.
* @param destValid time series (with time indices the same as destination)
* indicating whether each variable of the destination at that point is valid.
*/
public void setObservations(double[][] source, double[][] destination,
boolean[][] sourceValid, boolean[][] destValid) throws Exception;

35
java/source/infodynamics/measures/continuous/TransferEntropyCalculator.java
View File

@ -1,9 +1,44 @@
package infodynamics.measures.continuous;
/**
* <p>This specifies the interface for implementations of
* the transfer entropy (see Schreiber, PRL, 2000)
* and local transfer entropy (see Lizier et al, PRE, 2008).
* This is the <i>apparent</i> transfer entropy; i.e.
* we compute the transfer that appears to come from a single
* source variable, without examining any other potential sources
* (see Lizier et al, PRE, 2008).</p>
*
* <p>Specifically, this specifies the interface for computing
* the transfer entropy for <i>continuous</i>-valued variables.</p>
*
* @see "Schreiber, Physical Review Letters 85 (2) pp.461-464, 2000;
* <a href='http://dx.doi.org/10.1103/PhysRevLett.85.461'>download</a>
* (for definition of transfer entropy)"
* @see "Lizier, Prokopenko and Zomaya, Physical Review E 77, 026110, 2008;
* <a href='http://dx.doi.org/10.1103/PhysRevE.77.026110'>download</a>
* (for definition of <i>local</i> transfer entropy and qualification
* of naming it as <i>apparent</i> transfer entropy)"
*
* @author Joseph Lizier, <a href="joseph.lizier at gmail.com">email</a>,
* <a href="http://lizier.me/joseph/">www</a>
*
*/
public interface TransferEntropyCalculator extends ChannelCalculator {
/**
* Property name to specify the history length k
*/
public static final String K_PROP_NAME = "k_HISTORY";
/**
* Initialise the calculator for re-use with new observations.
* A new history length k can be supplied here; all other parameters
* remain unchanged.
*
* @param k history length to be considered.
* @throws Exception
*/
public void initialise(int k) throws Exception;
}

41
java/source/infodynamics/measures/continuous/TransferEntropyCalculatorMultiVariate.java
View File

@ -1,16 +1,47 @@
package infodynamics.measures.continuous;
/**
* <p>
* Interface to define computers for transfer entropy between a multi-variate source
* and destination.
* </p>
* <p>This specifies the interface for implementations of
* the transfer entropy (see Schreiber, PRL, 2000)
* and local transfer entropy (see Lizier et al, PRE, 2008).
* This is the <i>apparent</i> transfer entropy; i.e.
* we compute the transfer that appears to come from a single
* source variable, without examining any other potential sources
* (see Lizier et al, PRE, 2008).</p>
*
* @author Joseph Lizier; joseph.lizier at gmail.com
* <p>Specifically, this specifies the interface for computing
* the transfer entropy for <i>continuous</i>-valued,
* <i>multivariate</i> sources and destinations.</p>
*
*
* @see "Schreiber, Physical Review Letters 85 (2) pp.461-464, 2000;
* <a href='http://dx.doi.org/10.1103/PhysRevLett.85.461'>download</a>
* (for definition of transfer entropy)"
* @see "Lizier, Prokopenko and Zomaya, Physical Review E 77, 026110, 2008;
* <a href='http://dx.doi.org/10.1103/PhysRevE.77.026110'>download</a>
* (for definition of <i>local</i> transfer entropy and qualification
* of naming it as <i>apparent</i> transfer entropy)"
* @see "J.T. Lizier, J. Heinzle, A. Horstmann, J.-D. Haynes, M. Prokopenko,
* Journal of Computational Neuroscience, vol. 30, pp. 85-107, 2011
* <a href='http://dx.doi.org/10.1007/s10827-010-0271-2'>download</a>
* (for definition of <i>multivariate</i> transfer entropy"
*
* @author Joseph Lizier, <a href="joseph.lizier at gmail.com">email</a>,
* <a href="http://lizier.me/joseph/">www</a>
*
*/
public interface TransferEntropyCalculatorMultiVariate extends ChannelCalculatorMultiVariate {
/**
* Initialise the calculator for re-use with new observations.
* History length k, source and destination dimensions are
* specified here; all other parameters remain unchanged.
*
* @param k history length to be considered
* @param sourceDimensions number of joint variables in the source
* @param destDimensions number of joint variables in the destination
* @throws Exception
*/
public void initialise(int k, int sourceDimensions, int destDimensions) throws Exception;
}

103
java/source/infodynamics/measures/continuous/TransferEntropyCommon.java
View File

@ -6,16 +6,27 @@ import java.util.Vector;
/**
* <p>Base class for implementations of the transfer entropy,
* e.g. kernel estimation, Kraskov style extensions.
* It implements some common code to be used across transfer entropy calculators
* </p>
* <p>Base class for implementations of the transfer entropy (see Schreiber, PRL, 2000)
* and local transfer entropy (see Lizier et al, PRE, 2008).
* We use the term <i>apparent</i> transfer entropy to mean that
* we compute the transfer that appears to come from a single
* source variable, without examining any other potential sources
* (see Lizier et al, PRE, 2008).</p>
*
* <p>Specifically, this provides base implementations of the transfer entropy for
* <i>continuous</i>-valued variables (univariate).
* It provides common code used in multiple child implementations.</p>
*
* @author Joseph Lizier, joseph.lizier at gmail.com
*
* @see For transfer entropy: Schreiber, PRL 85 (2) pp.461-464, 2000; http://dx.doi.org/10.1103/PhysRevLett.85.461
* @see For local transfer entropy: Lizier et al, PRE 77, 026110, 2008; http://dx.doi.org/10.1103/PhysRevE.77.026110
* @see "Schreiber, Physical Review Letters 85 (2) pp.461-464, 2000;
* <a href='http://dx.doi.org/10.1103/PhysRevLett.85.461'>download</a>
* (for definition of transfer entropy)"
* @see "Lizier, Prokopenko and Zomaya, Physical Review E 77, 026110, 2008;
* <a href='http://dx.doi.org/10.1103/PhysRevE.77.026110'>download</a>
* (for definition of <i>local</i> transfer entropy and qualification
* of naming it as <i>apparent</i> transfer entropy)"
*
* @author Joseph Lizier, <a href="joseph.lizier at gmail.com">email</a>,
* <a href="http://lizier.me/joseph/">www</a>
*/
public abstract class TransferEntropyCommon implements
TransferEntropyCalculator {
@ -51,10 +62,14 @@ public abstract class TransferEntropyCommon implements
}
/**
* Set the observations to compute the probabilities from
* <p>Sets the single set of observations to compute the PDFs from.
* Cannot be called in conjunction with
* {@link #startAddObservations()}/{@link #addObservations(double[], double[])} /
* {@link #finaliseAddObservations()}.</p>
*
* @param source
* @param destination
* @param source observations for the source variable
* @param destination observations for the destination variable
* @throws Exception
*/
public void setObservations(double[] source, double[] destination) throws Exception {
startAddObservations();
@ -72,12 +87,27 @@ public abstract class TransferEntropyCommon implements
}
/**
* Add some more observations.
* Note that the arrays source and destination must not be over-written by the user
* until after finaliseAddObservations() has been called.
* <p>Adds a new set of observations to update the PDFs with - is
* intended to be called multiple times.
* Must be called after {@link #startAddObservations()}; call
* {@link #finaliseAddObservations()} once all observations have
* been supplied.</p>
*
* @param source
* @param destination
* <p><b>Important:</b> this does not append these observations to the previously
* supplied observations, but treats them independently - i.e. this
* will not join them up to examine k
* consecutive values in time (which would be an incorrect transfer entropy
* calculation, since the end of one observation set should not
* necessarily be followed by the start of another).</p>
*
* <p>Note that the arrays source and destination must not be over-written by the user
* until after finaliseAddObservations() has been called
* (they are not copied by this method necessarily, but the method
* may simply hold a pointer to them).</p>
*
* @param source observations for the source variable
* @param destination observations for the destination variable
* @throws Exception
*/
public void addObservations(double[] source, double[] destination) throws Exception {
if (vectorOfSourceObservations == null) {
@ -97,12 +127,29 @@ public abstract class TransferEntropyCommon implements
}
/**
* Add some more observations.
* <p>Adds a new set of observations to update the PDFs with - is
* intended to be called multiple times.
* Must be called after {@link #startAddObservations()}; call
* {@link #finaliseAddObservations()} once all observations have
* been supplied.</p>
*
* @param source
* @param destination
* <p><b>Important:</b> this does not append these observations to the previously
* supplied observations, but treats them independently - i.e. this
* will not join them up to examine k
* consecutive values in time (which would be an incorrect transfer entropy
* calculation, since the end of one observation set should not
* necessarily be followed by the start of another).</p>
*
* <p>Note that the arrays source and destination must not be over-written by the user
* until after finaliseAddObservations() has been called
* (they are not copied by this method necessarily, but the method
* may simply hold a pointer to them).</p>
*
* @param source observations for the source variable
* @param destination observations for the destination variable
* @param startTime first time index to take observations on
* @param numTimeSteps number of time steps to use
* @throws Exception
*/
public void addObservations(double[] source, double[] destination,
int startTime, int numTimeSteps) throws Exception {
@ -123,18 +170,18 @@ public abstract class TransferEntropyCommon implements
}
/**
* Sets the observations to compute the PDFs from.
* Cannot be called in conjunction with start/add/finaliseAddObservations.
* destValid is a time series (with time indices the same as destination)
* indicating whether the destination at that point is valid.
* sourceValid is the same for the source
* <p>Sets the single set of observations to compute the PDFs from.
* Cannot be called in conjunction with
* {@link #startAddObservations()}/{@link #addObservations(double[], double[])} /
* {@link #finaliseAddObservations()}.</p>
*
* @param source observations for the source variable
* @param destination observations for the destination variable
* @param sourceValid array indicating whether the source values
* are valid at each time step.
* @param destValid array indicating whether the destination values
* are valid at each time step.
* @param sourceValid time series (with time indices the same as source)
* indicating whether the source at that point is valid.
* @param destValid time series (with time indices the same as destination)
* indicating whether the destination at that point is valid.
* @throws Exception
*/
public void setObservations(double[] source, double[] destination,
boolean[] sourceValid, boolean[] destValid) throws Exception {

33
java/source/infodynamics/measures/continuous/kernel/TransferEntropyCalculatorMultiVariateKernel.java
View File

@ -201,10 +201,16 @@ public class TransferEntropyCalculatorMultiVariateKernel
}
/**
* Set the observations to compute the probabilities from
* <p>Sets the single set of observations to compute the PDFs from.
* Cannot be called in conjunction with
* {@link #startAddObservations()}/{@link #addObservations(double[], double[])} /
* {@link #finaliseAddObservations()}.</p>
*
* @param source
* @param destination
* @param source multivariate observations for the source variable
* (first index is time, second is variable number)
* @param destination multivariate observations for the destination variable
* (first index is time, second is variable number)
* @throws Exception
*/
public void setObservations(double[][] source, double[][] destination) throws Exception {
startAddObservations();
@ -213,16 +219,19 @@ public class TransferEntropyCalculatorMultiVariateKernel
}
/**
* Sets the observations to compute the PDFs from.
* Cannot be called in conjunction with start/add/finaliseAddObservations.
* destValid is a time series (with time indices the same as destination)
* indicating whether the destination at that point is valid.
* sourceValid is the same for the source
* <p>Sets the single set of observations to compute the PDFs from.
* Cannot be called in conjunction with
* {@link #startAddObservations()}/{@link #addObservations(double[], double[])} /
* {@link #finaliseAddObservations()}.</p>
*
* @param source observations for the source variable
* @param destination observations for the destination variable
* @param sourceValid
* @param destValid
* @param source multivariate observations for the source variable
* (first index is time, second is variable number)
* @param destination multivariate observations for the destination variable
* (first index is time, second is variable number)
* @param sourceValid time series (with time indices the same as source)
* indicating whether the source at that point is valid.
* @param destValid time series (with time indices the same as destination)
* indicating whether the destination at that point is valid.
*/
public void setObservations(double[][] source, double[][] destination, boolean[] sourceValid, boolean[] destValid) throws Exception {
Vector<int[]> startAndEndTimePairs = computeStartAndEndTimePairs(sourceValid, destValid);

57
java/source/infodynamics/measures/discrete/ApparentTransferEntropyCalculator.java
View File

@ -5,24 +5,51 @@ import infodynamics.utils.EmpiricalMeasurementDistribution;
import infodynamics.utils.RandomGenerator;
/**
* Implements transfer entropy (see Schreiber, PRL, 2000)
* and local transfer entropy (see Lizier et al, PRE, 2008)
* <p>Implements transfer entropy (see Schreiber, PRL, 2000)
* and local transfer entropy (see Lizier et al, PRE, 2008).
* We use the term <i>apparent</i> transfer entropy to mean that
* we compute the transfer that appears to come from a single
* source variable, without examining any other potential sources
* (see Lizier et al, PRE, 2008).</p>
*
* Usage:
* 0. Construct or call newInstance
* 1. Continuous accumulation of observations before computing :
* Call: a. initialise()
* b. addObservations() several times over
* c. computeLocalFromPreviousObservations() or computeAverageLocalOfObservations()
* 2. Standalone computation from a single set of observations:
* Call: computeLocal() or computeAverageLocal()
* <p>Specifically, this implements the transfer entropy for
* <i>discrete</i>-valued variables.</p>
*
* @see For transfer entropy: Schreiber, PRL 85 (2) pp.461-464, 2000; http://dx.doi.org/10.1103/PhysRevLett.85.461
* @see For local transfer entropy: Lizier et al, PRE 77, 026110, 2008; http://dx.doi.org/10.1103/PhysRevE.77.026110
* <p>Usage:
* <ol>
* <li>Construct: {@link #ApparentTransferEntropyCalculator(int, int)}</li>
* <li>Initialise: {@link #initialise()}</li>
* <li>Either:
* <ol>
* <li>Continuous accumulation of observations then measurement; call:
* <ol>
* <li>{@link #addObservations(int[], int[])} or related calls
* several times over - <b>note:</b> each method call adding
* observations can be viewed as updating the PDFs; they do not
* append the separate time series (this would be incorrect behaviour
* for the transfer entropy, since the start of one time series
* is not necessarily related to the end of the other).</li>
* <li>The compute relevant quantities, e.g.
* {@link #computeLocalFromPreviousObservations(int[], int[])} or
* {@link #computeAverageLocalOfObservations()}</li>
* </ol>
* <li>or Standalone computation from a single set of observations;
* call e.g.: {@link #computeLocal(int[], int[])} or
* {@link #computeAverageLocal(int[][], int)}.>/li>
* </ol>
* </ol>
* </p>
*
* @author Joseph Lizier
* joseph.lizier at gmail.com
* http://lizier.me/joseph/
* @see "Schreiber, Physical Review Letters 85 (2) pp.461-464, 2000;
* <a href='http://dx.doi.org/10.1103/PhysRevLett.85.461'>download</a>
* (for definition of transfer entropy)"
* @see "Lizier, Prokopenko and Zomaya, Physical Review E 77, 026110, 2008;
* <a href='http://dx.doi.org/10.1103/PhysRevE.77.026110'>download</a>
* (for definition of <i>local</i> transfer entropy and qualification
* of naming it as <i>apparent</i> transfer entropy)"
*
* @author Joseph Lizier, <a href="joseph.lizier at gmail.com">email</a>,
* <a href="http://lizier.me/joseph/">www</a>
*
*/
public class ApparentTransferEntropyCalculator extends ContextOfPastMeasureCalculator

65
java/source/infodynamics/measures/discrete/CompleteTransferEntropyCalculator.java
View File

@ -7,31 +7,68 @@ import infodynamics.utils.RandomGenerator;
/**
* Implements complete transfer entropy (see Lizier et al, PRE, 2008)
* Complete transfer entropy = transfer entropy conditioned on all causal information
* <p>Implements complete transfer entropy,
* and local complete transfer entropy (see Lizier et al, PRE, 2008).
* Complete transfer entropy is the transfer entropy <i>conditioned</i> on all causal information
* contributors to the destination.
* This class can also be used for incrementally conditioned mutual information terms
* This class can of course be used for any general conditional transfer entropy
* (see Lizier et al, Chaos 2010) by only supplying a limited
* number of the causal information contributors in the array of other agents to be
* number of sources in the array of other variables to be
* conditioned on.
* The causal information contributors (either their offsets or their absolute column numbers)
* The causal information contributors (specified using either their
* offsets from the destination variable or their absolute column numbers
* in the multivariate data set)
* should be supplied in the same order in every method call, otherwise the answer supplied will
* be incorrect.
* </p>
*
* Ideally, this class would extend ContextOfPastMeasure, however
* <p>Specifically, this implements the complete transfer entropy for
* <i>discrete</i>-valued variables.</p>
*
* <p>Ideally, this class would extend ContextOfPastMeasure, however
* by conditioning on other info contributors, we need to alter
* the arrays pastCount and nextPastCount to consider all
* conditioned variables (i.e. other sources) also.
* </p>
*
* Usage:
* 1. Continuous accumulation of observations:
* Call: a. initialise()
* b. addObservations() several times over
* c. computeLocalFromPreviousObservations()
* 2. Standalone:
* Call: localActiveInformation()
* <p>Usage:
* <ol>
* <li>Construct: {@link #CompleteTransferEntropyCalculator(int, int)}</li>
* <li>Initialise: {@link #initialise()}</li>
* <li>Either:
* <ol>
* <li>Continuous accumulation of observations then measurement; call:
* <ol>
* <li>{@link #addObservations(int[][], int, int[])} or related calls
* several times over - <b>note:</b> each method call adding
* observations can be viewed as updating the PDFs; they do not
* append the separate time series (this would be incorrect behaviour
* for the transfer entropy, since the start of one time series
* is not necessarily related to the end of the other).</li>
* <li>The compute relevant quantities, e.g.
* {@link #computeLocalFromPreviousObservations(int[][], int, int[])} or
* {@link #computeAverageLocalOfObservations()}</li>
* </ol>
* <li>or Standalone computation from a single set of observations;
* call e.g.: {@link #computeLocal(int[][], int, int[])} or
* {@link #computeAverageLocal(int[][], int, int, int[])}.>/li>
* </ol>
* </ol>
* </p>
*
* @author Joseph Lizier
* @see "Schreiber, Physical Review Letters 85 (2) pp.461-464, 2000;
* <a href='http://dx.doi.org/10.1103/PhysRevLett.85.461'>download</a>
* (for definition of transfer entropy)"
* @see "Lizier, Prokopenko and Zomaya, Physical Review E 77, 026110, 2008;
* <a href='http://dx.doi.org/10.1103/PhysRevE.77.026110'>download</a>
* (for definition of <i>local</i> transfer entropy and
* <i>complete</i> transfer entropy)"
* @see "Lizier, Prokopenko and Zomaya, Chaos vol. 20, no. 3, 037109, 2010;
* <a href='http://dx.doi.org/10.1063/1.3486801'>download</a>
* (for definition of <i>conditional</i> transfer entropy)"
*
* @author Joseph Lizier, <a href="joseph.lizier at gmail.com">email</a>,
* <a href="http://lizier.me/joseph/">www</a>
*
*/
public class CompleteTransferEntropyCalculator extends InfoMeasureCalculator {