From 8129dbee7b3f788385f2a33fcddc52ab4a8896bd Mon Sep 17 00:00:00 2001 From: "joseph.lizier" Date: Wed, 8 Aug 2012 05:33:13 +0000 Subject: [PATCH] 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. --- .../continuous/ChannelCalculator.java | 76 +++++++++--- .../continuous/ChannelCalculatorCommon.java | 31 ++++- .../ChannelCalculatorMultiVariate.java | 111 ++++++++++++++---- .../continuous/TransferEntropyCalculator.java | 35 ++++++ ...TransferEntropyCalculatorMultiVariate.java | 41 ++++++- .../continuous/TransferEntropyCommon.java | 103 +++++++++++----- ...erEntropyCalculatorMultiVariateKernel.java | 33 ++++-- .../ApparentTransferEntropyCalculator.java | 57 ++++++--- .../CompleteTransferEntropyCalculator.java | 65 +++++++--- 9 files changed, 438 insertions(+), 114 deletions(-) diff --git a/java/source/infodynamics/measures/continuous/ChannelCalculator.java b/java/source/infodynamics/measures/continuous/ChannelCalculator.java index e855fc4..6ea60f7 100755 --- a/java/source/infodynamics/measures/continuous/ChannelCalculator.java +++ b/java/source/infodynamics/measures/continuous/ChannelCalculator.java @@ -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, email, + * www * */ public interface ChannelCalculator extends ChannelCalculatorCommon { public void initialise() throws Exception; + /** + *

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()}.

+ * + * @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. + *

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.

* - * @param source - * @param destination + *

Important: 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.

+ * + *

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).

+ * + * @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. + *

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.

* - * @param source - * @param destination + *

Important: 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.

+ * + *

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).

+ * + * @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 + *

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()}.

* * @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; diff --git a/java/source/infodynamics/measures/continuous/ChannelCalculatorCommon.java b/java/source/infodynamics/measures/continuous/ChannelCalculatorCommon.java index 17b82a8..35ca88c 100755 --- a/java/source/infodynamics/measures/continuous/ChannelCalculatorCommon.java +++ b/java/source/infodynamics/measures/continuous/ChannelCalculatorCommon.java @@ -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. + *

An abstract interface for calculators computing measures from a source to a destination. + *

+ * + *

The interface is abstract because further specification is required + * for addObservations or setObservations methods showing whether + * this is a univariate or multivariate measure.

* * - * @author Joseph Lizier, jlizier at gmail.com + * @author Joseph Lizier, email, + * www * */ 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; + /** + *

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).

+ * + *

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).

+ * + * @return array of local values. + * @throws Exception + */ public double[] computeLocalOfPreviousObservations() throws Exception; /** diff --git a/java/source/infodynamics/measures/continuous/ChannelCalculatorMultiVariate.java b/java/source/infodynamics/measures/continuous/ChannelCalculatorMultiVariate.java index 9637d35..2a18272 100755 --- a/java/source/infodynamics/measures/continuous/ChannelCalculatorMultiVariate.java +++ b/java/source/infodynamics/measures/continuous/ChannelCalculatorMultiVariate.java @@ -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, email, + * www * */ 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; + /** + *

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()}.

+ * + * @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; + /** + *

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.

+ * + *

Important: 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.

+ * + *

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).

+ * + * @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; + /** + *

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.

+ * + *

Important: 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.

+ * + *

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).

+ * + * @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 + *

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()}.

* - * @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 + *

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()}.

* - * @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; diff --git a/java/source/infodynamics/measures/continuous/TransferEntropyCalculator.java b/java/source/infodynamics/measures/continuous/TransferEntropyCalculator.java index 6173c3d..6224d94 100755 --- a/java/source/infodynamics/measures/continuous/TransferEntropyCalculator.java +++ b/java/source/infodynamics/measures/continuous/TransferEntropyCalculator.java @@ -1,9 +1,44 @@ package infodynamics.measures.continuous; +/** + *

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 apparent 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).

+ * + *

Specifically, this specifies the interface for computing + * the transfer entropy for continuous-valued variables.

+ * + * @see "Schreiber, Physical Review Letters 85 (2) pp.461-464, 2000; + * download + * (for definition of transfer entropy)" + * @see "Lizier, Prokopenko and Zomaya, Physical Review E 77, 026110, 2008; + * download + * (for definition of local transfer entropy and qualification + * of naming it as apparent transfer entropy)" + * + * @author Joseph Lizier, email, + * www + * + */ 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; } diff --git a/java/source/infodynamics/measures/continuous/TransferEntropyCalculatorMultiVariate.java b/java/source/infodynamics/measures/continuous/TransferEntropyCalculatorMultiVariate.java index 89f36be..0867395 100755 --- a/java/source/infodynamics/measures/continuous/TransferEntropyCalculatorMultiVariate.java +++ b/java/source/infodynamics/measures/continuous/TransferEntropyCalculatorMultiVariate.java @@ -1,16 +1,47 @@ package infodynamics.measures.continuous; /** - *

- * Interface to define computers for transfer entropy between a multi-variate source - * and destination. - *

+ *

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 apparent 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).

* - * @author Joseph Lizier; joseph.lizier at gmail.com + *

Specifically, this specifies the interface for computing + * the transfer entropy for continuous-valued, + * multivariate sources and destinations.

+ * + * + * @see "Schreiber, Physical Review Letters 85 (2) pp.461-464, 2000; + * download + * (for definition of transfer entropy)" + * @see "Lizier, Prokopenko and Zomaya, Physical Review E 77, 026110, 2008; + * download + * (for definition of local transfer entropy and qualification + * of naming it as apparent 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 + * download + * (for definition of multivariate transfer entropy" + * + * @author Joseph Lizier, email, + * www * */ 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; } diff --git a/java/source/infodynamics/measures/continuous/TransferEntropyCommon.java b/java/source/infodynamics/measures/continuous/TransferEntropyCommon.java index a4b758d..a77701d 100755 --- a/java/source/infodynamics/measures/continuous/TransferEntropyCommon.java +++ b/java/source/infodynamics/measures/continuous/TransferEntropyCommon.java @@ -6,16 +6,27 @@ import java.util.Vector; /** - *

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 - *

+ *

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 apparent 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).

* + *

Specifically, this provides base implementations of the transfer entropy for + * continuous-valued variables (univariate). + * It provides common code used in multiple child implementations.

* - * @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; + * download + * (for definition of transfer entropy)" + * @see "Lizier, Prokopenko and Zomaya, Physical Review E 77, 026110, 2008; + * download + * (for definition of local transfer entropy and qualification + * of naming it as apparent transfer entropy)" + * + * @author Joseph Lizier, email, + * www */ public abstract class TransferEntropyCommon implements TransferEntropyCalculator { @@ -51,10 +62,14 @@ public abstract class TransferEntropyCommon implements } /** - * Set the observations to compute the probabilities from + *

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()}.

* - * @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. + *

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.

* - * @param source - * @param destination + *

Important: 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).

+ * + *

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).

+ * + * @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. + *

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.

* - * @param source - * @param destination + *

Important: 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).

+ * + *

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).

+ * + * @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 + *

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()}.

* * @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 { diff --git a/java/source/infodynamics/measures/continuous/kernel/TransferEntropyCalculatorMultiVariateKernel.java b/java/source/infodynamics/measures/continuous/kernel/TransferEntropyCalculatorMultiVariateKernel.java index edabb4b..18d762b 100755 --- a/java/source/infodynamics/measures/continuous/kernel/TransferEntropyCalculatorMultiVariateKernel.java +++ b/java/source/infodynamics/measures/continuous/kernel/TransferEntropyCalculatorMultiVariateKernel.java @@ -201,10 +201,16 @@ public class TransferEntropyCalculatorMultiVariateKernel } /** - * Set the observations to compute the probabilities from + *

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()}.

* - * @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 + *

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()}.

* - * @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 startAndEndTimePairs = computeStartAndEndTimePairs(sourceValid, destValid); diff --git a/java/source/infodynamics/measures/discrete/ApparentTransferEntropyCalculator.java b/java/source/infodynamics/measures/discrete/ApparentTransferEntropyCalculator.java index 71423f0..177a05a 100755 --- a/java/source/infodynamics/measures/discrete/ApparentTransferEntropyCalculator.java +++ b/java/source/infodynamics/measures/discrete/ApparentTransferEntropyCalculator.java @@ -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) + *

Implements transfer entropy (see Schreiber, PRL, 2000) + * and local transfer entropy (see Lizier et al, PRE, 2008). + * We use the term apparent 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).

* - * 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() + *

Specifically, this implements the transfer entropy for + * discrete-valued variables.

* - * @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 + *

Usage: + *

    + *
  1. Construct: {@link #ApparentTransferEntropyCalculator(int, int)}
    2. + *
  2. Initialise: {@link #initialise()}
    3. + *
  3. Either: + *
      + *
    1. Continuous accumulation of observations then measurement; call: + *
        + *
      1. {@link #addObservations(int[], int[])} or related calls + * several times over - note: 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).
        2. + *
      2. The compute relevant quantities, e.g. + * {@link #computeLocalFromPreviousObservations(int[], int[])} or + * {@link #computeAverageLocalOfObservations()}
        3. + *
      + *
    2. or Standalone computation from a single set of observations; + * call e.g.: {@link #computeLocal(int[], int[])} or + * {@link #computeAverageLocal(int[][], int)}.>/li> + *
    + *
+ *

* - * @author Joseph Lizier - * joseph.lizier at gmail.com - * http://lizier.me/joseph/ + * @see "Schreiber, Physical Review Letters 85 (2) pp.461-464, 2000; + * download + * (for definition of transfer entropy)" + * @see "Lizier, Prokopenko and Zomaya, Physical Review E 77, 026110, 2008; + * download + * (for definition of local transfer entropy and qualification + * of naming it as apparent transfer entropy)" + * + * @author Joseph Lizier, email, + * www * */ public class ApparentTransferEntropyCalculator extends ContextOfPastMeasureCalculator diff --git a/java/source/infodynamics/measures/discrete/CompleteTransferEntropyCalculator.java b/java/source/infodynamics/measures/discrete/CompleteTransferEntropyCalculator.java index 33d9055..8f0286e 100755 --- a/java/source/infodynamics/measures/discrete/CompleteTransferEntropyCalculator.java +++ b/java/source/infodynamics/measures/discrete/CompleteTransferEntropyCalculator.java @@ -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 + *

Implements complete transfer entropy, + * and local complete transfer entropy (see Lizier et al, PRE, 2008). + * Complete transfer entropy is the transfer entropy conditioned 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. + *

* - * Ideally, this class would extend ContextOfPastMeasure, however + *

Specifically, this implements the complete transfer entropy for + * discrete-valued variables.

+ * + *

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. + *

* - * Usage: - * 1. Continuous accumulation of observations: - * Call: a. initialise() - * b. addObservations() several times over - * c. computeLocalFromPreviousObservations() - * 2. Standalone: - * Call: localActiveInformation() + *

Usage: + *

    + *
  1. Construct: {@link #CompleteTransferEntropyCalculator(int, int)}
    2. + *
  2. Initialise: {@link #initialise()}
    3. + *
  3. Either: + *
      + *
    1. Continuous accumulation of observations then measurement; call: + *
        + *
      1. {@link #addObservations(int[][], int, int[])} or related calls + * several times over - note: 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).
        2. + *
      2. The compute relevant quantities, e.g. + * {@link #computeLocalFromPreviousObservations(int[][], int, int[])} or + * {@link #computeAverageLocalOfObservations()}
        3. + *
      + *
    2. 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> + *
    + *
+ *

* - * @author Joseph Lizier + * @see "Schreiber, Physical Review Letters 85 (2) pp.461-464, 2000; + * download + * (for definition of transfer entropy)" + * @see "Lizier, Prokopenko and Zomaya, Physical Review E 77, 026110, 2008; + * download + * (for definition of local transfer entropy and + * complete transfer entropy)" + * @see "Lizier, Prokopenko and Zomaya, Chaos vol. 20, no. 3, 037109, 2010; + * download + * (for definition of conditional transfer entropy)" + * + * @author Joseph Lizier, email, + * www * */ public class CompleteTransferEntropyCalculator extends InfoMeasureCalculator {