added in the original spiking estimator code

java/source/infodynamics/measures/spiking/TransferEntropyCalculatorSpiking.java

@@ -0,0 +1,362 @@
+/*
+ *  Java Information Dynamics Toolkit (JIDT)
+ *  Copyright (C) 2012, Joseph T. Lizier
+ *  
+ *  This program is free software: you can redistribute it and/or modify
+ *  it under the terms of the GNU General Public License as published by
+ *  the Free Software Foundation, either version 3 of the License, or
+ *  (at your option) any later version.
+ *  
+ *  This program is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ *  GNU General Public License for more details.
+ *  
+ *  You should have received a copy of the GNU General Public License
+ *  along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+package infodynamics.measures.spiking;
+
+import infodynamics.utils.EmpiricalMeasurementDistribution;
+
+/**
+ * <p>Interface for implementations of the <b>transfer entropy</b> (TE),
+ * which may be applied to spiking time-series data.
+ * That is, it is applied to <code>double[]</code> data, as an array
+ * of time stamps at which spikes were recorded.
+ * See Schreiber below for the definition of transfer entropy,
+ * and Lizier et al. for the definition of local transfer entropy,
+ * and (To be published) for how to measure transfer entropy on spike trains.
+ * Specifically, this class implements the pairwise or <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>
+ * Usage of the child classes implementing this interface is intended to follow this paradigm:
+ * </p>
+ * 	<ol>
+ * 		<li>Construct the calculator;</li>
+ * 		<li>Set properties using {@link #setProperty(String, String)}
+ * 			e.g. including properties describing
+ * 			the source and destination embedding;</li>
+ *		<li>Initialise the calculator using
+ *			{@link #initialise()} or {@link #initialise(int, int)};</li>
+ * 		<li>Provide the observations/samples for the calculator
+ *      	to set up the PDFs, using:
+ * 			<ul>
+ * 				<li>{@link #setObservations(double[], double[])} 
+ * 					for calculations based on single recordings, OR</li>
+ * 				<li>The following sequence:<ol>
+ * 						<li>{@link #startAddObservations()}, then</li>
+ * 						<li>One or more calls to
+ * 							{@link #addObservations(double[], double[])}, then</li>
+ * 						<li>{@link #finaliseAddObservations()};</li>
+ * 					</ol></li>
+ * 			</ul></li>
+ * 		<li>Compute the required quantities, being one or more of:
+ * 			<ul>
+ * 				<li>the average TE: {@link #computeAverageLocalOfObservations()};</li>
+ * 				<li>the local TE values for these samples: {@link #computeLocalOfPreviousObservations()}</li>
+ * 				<li>the distribution of TE values under the null hypothesis
+ * 					of no relationship between source and
+ * 					destination values: {@link #computeSignificance(int)} or
+ * 					{@link #computeSignificance(int[][])}.</li>
+ * 			</ul>
+ * 		</li>
+ * 		<li>
+ * 		Return to step 2 or 3 to re-use the calculator on a new data set.
+ * 		</li>
+ * 	</ol>
+ * </p>
+ * 
+ * <p><b>References:</b><br/>
+ * <ul>
+ * 	<li>T. Schreiber, <a href="http://dx.doi.org/10.1103/PhysRevLett.85.461">
+ * "Measuring information transfer"</a>,
+ *  Physical Review Letters 85 (2) pp.461-464, 2000.</li>
+ *  <li>J. T. Lizier, M. Prokopenko and A. Zomaya,
+ *  <a href="http://dx.doi.org/10.1103/PhysRevE.77.026110">
+ *  "Local information transfer as a spatiotemporal filter for complex systems"</a>
+ *  Physical Review E 77, 026110, 2008.</li>
+ *  <li>To be published</li>
+ * </ul>
+ *
+ * @author Joseph Lizier (<a href="joseph.lizier at gmail.com">email</a>,
+ * <a href="http://lizier.me/joseph/">www</a>)
+ */
+public interface TransferEntropyCalculatorSpiking {
+
+	/**
+	 * Property name to specify the destination history embedding length k
+	 * (default value 1)
+	 */
+	public static final String K_PROP_NAME = "k_HISTORY";
+	/**
+	 * Property name for embedding length for the source past history vector
+	 * (default value 1)
+	 */
+	public static final String L_PROP_NAME = "l_HISTORY";
+	/* Could try to do this one later. I think we would just consider the history 
+	 * of source as being up to this many units of time behind destination and
+	 * no later. 
+	 * 
+	 * Property name for source-destination delay (default value is 0)
+	 *
+	public static final String DELAY_PROP_NAME = "DELAY";
+	 */
+	/**
+	 * Property name for whether each series of time stamps of spikes is sorted
+	 *  into temporal order. (default true)
+	 */
+	public static final String TIMESORTED_PROP_NAME = "TIME_SORTED";
+	
+	/**
+	 * Initialise the calculator for re-use with new observations.
+	 * All parameters remain unchanged.
+	 * 
+	 * @throws Exception
+	 */
+	public void initialise() throws Exception;
+	
+	/**
+	 * Initialise the calculator for re-use with new observations.
+	 * A new history embedding length k can be supplied here; all other parameters
+	 * remain unchanged.
+	 * 
+	 * @param k destination history embedding length to be considered.
+	 * @throws Exception
+	 */
+	public void initialise(int k) throws Exception;
+	
+	/**
+	 * Initialise the calculator for re-use with new observations.
+	 * New history embedding lengths k and l can be supplied here; all other parameters
+	 * remain unchanged.
+	 * 
+	 * @param k destination history embedding length to be considered.
+	 * @param l source history embedding length to be considered.
+	 * @throws Exception
+	 */
+	public void initialise(int k, int l) throws Exception;
+
+	/**
+	 * Sets properties for the TE calculator.
+	 *  New property values are not guaranteed to take effect until the next call
+	 *  to an initialise method. 
+	 *  
+	 * <p>Valid property names, and what their
+	 * values should represent, include:</p>
+	 * <ul>
+	 * 		<li>{@link #K_PROP_NAME} -- destination history embedding length k
+	 * 			(default value 1)</li>
+	 * 		<li>{@link #L_PROP_NAME} -- embedding length for the source past history vector
+	 * 			(default value 1)</li>
+	 * 		<li>{@link #TIMESORTED_PROP_NAME} --  whether each series of time stamps of spikes is sorted
+	 *  		into temporal order. (default "true")</li>
+	 * </ul>
+	 * <p><b>Note:</b> further properties may be defined by child classes.</p>
+	 * 
+	 * <p>Unknown property values are ignored.</p>
+	 * 
+	 * @param propertyName name of the property
+	 * @param propertyValue value of the property.
+	 * @throws Exception if there is a problem with the supplied value, 
+	 * or if the property is recognised but unsupported (eg some
+	 * calculators do not support all of the embedding properties).
+	 */
+	public void setProperty(String propertyName, String propertyValue) throws Exception;
+
+	/**
+	 * Get current property values for the calculator.
+	 * 
+	 * <p>Valid property names, and what their
+	 * values should represent, are the same as those for
+	 * {@link #setProperty(String, String)}</p>
+	 * 
+	 * <p>Unknown property values are responded to with a null return value.</p>
+	 * 
+	 * @param propertyName name of the property
+	 * @return current value of the property
+	 * @throws Exception for invalid property values
+	 */
+	public String getProperty(String propertyName) throws Exception;
+	
+	/**
+	 * Sets a single set of spiking observations from which to compute the PDF for transfer entropy.
+	 * Cannot be called in conjunction with other methods for setting/adding
+	 * observations.
+	 * 
+	 * @param source series of time stamps of spikes for the source variable. 
+	 * @param destination series of time stamps of spikes for the destination
+	 *  variable. Length will generally be different to the <code>source</code>, 
+	 *  unlike other transfer entropy implementations, e.g. for {@link infodynamics.measures.continuous.TransferEntropyCalculator}.
+	 *   <code>source</code> and  <code>destination</code> must have the same reference time point,
+	 *   and each array is assumed to be sorted into temporal order unless
+	 *   the property {@link #TIMESORTED_PROP_NAME} has been set to false.
+	 *  
+	 * @throws Exception
+	 */
+	public void setObservations(double source[], double destination[]) throws Exception;
+	
+	/**
+	 * Signal that we will add in the samples for computing the PDF 
+	 * from several disjoint time-series or trials via calls to
+	 * {@link #addObservations(double[], double[])} rather than 
+	 * {@link #setObservations(double[], double[])} type methods
+	 * (defined by the child interfaces and classes).
+	 *
+	 */
+	public void startAddObservations();
+	
+	/**
+	 * <p>Adds a new set of spiking observations to update the PDFs with.
+	 * It is intended to be called multiple times, and must
+	 * be called after {@link #startAddObservations()}. Call
+	 * {@link #finaliseAddObservations()} once all observations have
+	 * been supplied.</p>
+	 * 
+	 * <p><b>Important:</b> this does not append or overlay these observations to the previously
+	 *  supplied observations, but treats them as independent trials - 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 {@link #finaliseAddObservations()} has been called
+	 *  (they are not copied by this method necessarily, the method
+	 *  may simply hold a pointer to them).</p>
+	 * 
+	 * @param source series of time stamps of spikes for the source variable. 
+	 *   Will be returned in ascending sorted order.
+	 * @param destination series of time stamps of spikes for the destination
+	 *  variable. Length will generally be different to the <code>source</code>, 
+	 *  unlike other transfer entropy implementations, e.g. for {@link infodynamics.measures.continuous.TransferEntropyCalculator}.
+	 *   <code>source</code> and  <code>destination</code> must have the same reference time point,
+	 *   and each array is assumed to be sorted into temporal order unless
+	 *   the property {@link #TIMESORTED_PROP_NAME} has been set to false.
+	 *   Will be returned in ascending sorted order.
+	 * @throws Exception
+	 */
+	public void addObservations(double[] source, double[] destination) throws Exception;
+
+	/**
+	 * Signal that the observations are now all added via
+	 * {@link #addObservations(double[], double[])}, PDFs can now be constructed.
+	 * 
+	 * @throws Exception 
+	 */
+	public void finaliseAddObservations() throws Exception;
+	
+	/**
+	 * Query whether the user has added more than a single observation set via the
+	 *  {@link #startAddObservations()}, "addObservations" (defined by child interfaces
+	 *  and classes), {@link #finaliseAddObservations()} sequence.
+	 * 
+	 * @return true if more than a single observation set was supplied
+	 */
+	public boolean getAddedMoreThanOneObservationSet();
+	
+	/**
+	 * Compute the TE from the previously-supplied samples.
+	 * 
+	 * @return the estimate of the channel measure
+	 */
+	public double computeAverageLocalOfObservations() throws Exception;
+
+	/**
+	 * This interface serves to indicate the return type of {@link TransferEntropyCalculator#computeLocalOfPreviousObservations()}
+	 *  as each child implementation will return something specific
+	 * 
+	 * @author Joseph Lizier
+	 *
+	 */
+	public interface SpikingLocalInformationValues {
+		// Left empty intentionally
+	}
+	
+	/**
+	 * @return an object containing a representation of 
+	 *   the of local TE values. The precise contents of this representation
+	 *   will vary depending on the underlying implementation
+	 */
+	public SpikingLocalInformationValues computeLocalOfPreviousObservations() throws Exception;
+	
+	/**
+	 * Generate a bootstrapped distribution of what the TE would look like,
+	 * under a null hypothesis that the source values of our
+	 * samples had no temporal relation to the destination value.
+	 * 
+	 * <p>See Section II.E "Statistical significance testing" of 
+	 * the JIDT paper below for a description of how this is done for MI and TE in general.
+	 * </p>
+	 * 
+	 * <p>Note that if several disjoint time-series have been added 
+	 * as observations using {@link #addObservations(double[])} etc.,
+	 * then these separate "trials" will be mixed up in the generation
+	 * of surrogates here.</p>
+	 * 
+	 * <p>This method (in contrast to {@link #computeSignificance(int[][])})
+	 * creates <i>random</i> shufflings of the source embedding vectors for the surrogate
+	 * calculations.</p>
+	 * 
+	 * @param numPermutationsToCheck number of surrogate samples to bootstrap
+	 *  to generate the distribution.
+	 * @return the distribution of TE scores under this null hypothesis.
+	 * @see "J.T. Lizier, 'JIDT: An information-theoretic
+	 *    toolkit for studying the dynamics of complex systems', 2014."
+	 */
+	public EmpiricalMeasurementDistribution computeSignificance(int numPermutationsToCheck) throws Exception;
+	
+	/**
+	 * Generate a bootstrapped distribution of what the TE would look like,
+	 * under a null hypothesis that the source values of our
+	 * samples had no relation to the destination value.
+	 * 
+	 * <p>See Section II.E "Statistical significance testing" of 
+	 * the JIDT paper below for a description of how this is done for MI and TE.
+	 * </p>
+	 * 
+	 * <p>Note that if several disjoint time-series have been added 
+	 * as observations using {@link #addObservations(double[])} etc.,
+	 * then these separate "trials" will be mixed up in the generation
+	 * of surrogates here.</p>
+	 * 
+	 * <p>This method (in contrast to {@link #computeSignificance(int)})
+	 * allows the user to specify how to construct the surrogates,
+	 * such that repeatable results may be obtained.</p>
+	 * 
+	 * @param newOrderings a specification of how to shuffle the source embedding vectors
+	 *  between all of our samples to create the surrogates to generate the distribution with. The first
+	 *  index is the permutation number (i.e. newOrderings.length is the number
+	 *  of surrogate samples we use to bootstrap to generate the distribution here.)
+	 *  Each array newOrderings[i] should be an array of length N (where
+	 *  would be the value returned by {@link #getNumObservations()}),
+	 *  containing a permutation of the values in 0..(N-1).
+	 *  TODO Need to think this through a little more before implementing.
+	 * @return the distribution of channel measure scores under this null hypothesis.
+	 * @see "J.T. Lizier, 'JIDT: An information-theoretic
+	 *    toolkit for studying the dynamics of complex systems', 2014."
+	 * @throws Exception where the length of each permutation in newOrderings
+	 *   is not equal to the number N samples that were previously supplied.
+	 */
+	public EmpiricalMeasurementDistribution computeSignificance(
+			int[][] newOrderings) throws Exception;
+
+	/**
+	 * Set or clear debug mode for extra debug printing to stdout
+	 * 
+	 * @param debug new setting for debug mode (on/off)
+	 */
+	public void setDebug(boolean debug);
+	
+	/**
+	 * Return the TE last calculated in a call to {@link #computeAverageLocalOfObservations()}
+	 * or {@link #computeLocalOfPreviousObservations()} after the previous
+	 * {@link #initialise()} call.
+	 * 
+	 * @return the last computed channel measure value
+	 */
+	public double getLastAverage();
+}

java/source/infodynamics/measures/spiking/integration/package-info.java

@@ -0,0 +1,8 @@
+/**
+ * 
+ */
+/**
+ * @author joseph
+ *
+ */
+package infodynamics.measures.spiking.integration;

java/source/infodynamics/measures/spiking/package-info.java

@@ -0,0 +1,8 @@
+/**
+ * 
+ */
+/**
+ * @author joseph
+ *
+ */
+package infodynamics.measures.spiking;