mirror of https://github.com/jlizier/jidt
236 lines
10 KiB
Java
Executable File
236 lines
10 KiB
Java
Executable File
/*
|
|
* 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.continuous.kraskov;
|
|
|
|
import java.util.Hashtable;
|
|
|
|
import infodynamics.measures.continuous.ConditionalMutualInfoCalculatorMultiVariate;
|
|
import infodynamics.measures.continuous.ConditionalTransferEntropyCalculator;
|
|
import infodynamics.measures.continuous.ConditionalTransferEntropyCalculatorViaCondMutualInfo;
|
|
|
|
/**
|
|
* <p>Computes the differential conditional transfer entropy (TE) between two univariate
|
|
* <code>double[]</code> time-series of observations
|
|
* (implementing {@link ConditionalTransferEntropyCalculator}),
|
|
* using Kraskov-Stoegbauer-Grassberger (KSG) estimation (see references below).
|
|
* This estimator is realised here by plugging in
|
|
* a {@link ConditionalMutualInfoCalculatorMultiVariateKraskov}
|
|
* as the calculator into the parent class
|
|
* {@link ConditionalTransferEntropyCalculatorViaCondMutualInfo}.</p>
|
|
*
|
|
* <p>Crucially, the calculation is performed by examining
|
|
* neighbours in the full joint space (as specified by Frenzel and Pompe,
|
|
* and Gomez-Herrero et al.)
|
|
* rather than two MI calculators.</p>
|
|
*
|
|
* <p>Usage is as per the paradigm outlined for {@link ConditionalTransferEntropyCalculator},
|
|
* with:
|
|
* <ul>
|
|
* <li>The constructor step is either a simple call to
|
|
* {@link #ConditionalTransferEntropyCalculatorKraskov()},
|
|
* or else specifies which KSG algorithm to implement via
|
|
* {@link #ConditionalTransferEntropyCalculatorKraskov(String)};</li>
|
|
* <li>{@link #setProperty(String, String)} allowing properties defined for both
|
|
* {@link ConditionalTransferEntropyCalculator#setProperty(String, String)} and
|
|
* {@link ConditionalMutualInfoCalculatorMultiVariateKraskov#setProperty(String, String)}
|
|
* as outlined
|
|
* in {@link ConditionalTransferEntropyCalculatorViaCondMutualInfo#setProperty(String, String)});
|
|
* as well as for {@link #PROP_KRASKOV_ALG_NUM}.</li>
|
|
* <li>Computed values are in <b>nats</b>, not bits!</li>
|
|
* </ul>
|
|
* </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>Frenzel and Pompe, <a href="http://dx.doi.org/10.1103/physrevlett.99.204101">
|
|
* "Partial Mutual Information for Coupling Analysis of Multivariate Time Series"</a>,
|
|
* Physical Review Letters, <b>99</b>, p. 204101+ (2007).</li>
|
|
* <li>G. Gomez-Herrero, W. Wu, K. Rutanen, M. C. Soriano, G. Pipa, and R. Vicente,
|
|
* <a href="http://arxiv.org/abs/1008.0539">
|
|
* "Assessing coupling dynamics from an ensemble of time series"</a>,
|
|
* arXiv:1008.0539 (2010).</li>
|
|
* <li>Kraskov, A., Stoegbauer, H., Grassberger, P.,
|
|
* <a href="http://dx.doi.org/10.1103/PhysRevE.69.066138">"Estimating mutual information"</a>,
|
|
* Physical Review E 69, (2004) 066138.</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>J. T. Lizier, M. Prokopenko and A. Zomaya,
|
|
* <a href=http://dx.doi.org/10.1063/1.3486801">
|
|
* "Information modification and particle collisions in distributed computation"</a>
|
|
* Chaos 20, 3, 037109 (2010).</li>
|
|
* </ul>
|
|
*
|
|
* @author Joseph Lizier, <a href="joseph.lizier at gmail.com">email</a>,
|
|
* <a href="http://lizier.me/joseph/">www</a>
|
|
*
|
|
* @see ConditionalTransferEntropyCalculator
|
|
* @see ConditionalMutualInfoCalculatorMultiVariateKraskov
|
|
*/
|
|
public class ConditionalTransferEntropyCalculatorKraskov
|
|
extends ConditionalTransferEntropyCalculatorViaCondMutualInfo {
|
|
|
|
/**
|
|
* Class name for KSG conditional MI estimator via KSG algorithm 1
|
|
*/
|
|
public static final String COND_MI_CALCULATOR_KRASKOV1 = ConditionalMutualInfoCalculatorMultiVariateKraskov1.class.getName();
|
|
/**
|
|
* Class name for KSG conditional MI estimator via KSG algorithm 2
|
|
*/
|
|
public static final String COND_MI_CALCULATOR_KRASKOV2 = ConditionalMutualInfoCalculatorMultiVariateKraskov2.class.getName();
|
|
|
|
/**
|
|
* Property for setting which underlying Kraskov-Grassberger algorithm to use.
|
|
* Will only be applied at the next initialisation.
|
|
*/
|
|
public final static String PROP_KRASKOV_ALG_NUM = "ALG_NUM";
|
|
|
|
/**
|
|
* Which Kraskov algorithm number we are using
|
|
*/
|
|
protected int kraskovAlgorithmNumber = 1;
|
|
protected boolean algChanged = false;
|
|
/**
|
|
* Storage for the properties ready to pass onto the underlying conditional MI calculators should they change
|
|
*/
|
|
protected Hashtable<String,String> props;
|
|
|
|
/**
|
|
* Creates a new instance of the Kraskov-estimate style conditional transfer entropy calculator
|
|
*
|
|
* Uses algorithm 1 by default, as per Gomez-Herro et al.
|
|
*
|
|
* @throws ClassNotFoundException
|
|
* @throws IllegalAccessException
|
|
* @throws InstantiationException
|
|
*
|
|
*/
|
|
public ConditionalTransferEntropyCalculatorKraskov() throws InstantiationException, IllegalAccessException, ClassNotFoundException {
|
|
super(COND_MI_CALCULATOR_KRASKOV1);
|
|
kraskovAlgorithmNumber = 1;
|
|
props = new Hashtable<String,String>();
|
|
}
|
|
|
|
/**
|
|
* Creates a new instance of the Kraskov-Grassberger style conditional transfer entropy calculator,
|
|
* with the supplied conditional MI calculator name
|
|
*
|
|
* @param calculatorName fully qualified name of the underlying MI class.
|
|
* Must be {@link #COND_MI_CALCULATOR_KRASKOV1} or {@link #COND_MI_CALCULATOR_KRASKOV2}
|
|
* @throws ClassNotFoundException
|
|
* @throws IllegalAccessException
|
|
* @throws InstantiationException
|
|
*
|
|
*/
|
|
public ConditionalTransferEntropyCalculatorKraskov(String calculatorName) throws InstantiationException, IllegalAccessException, ClassNotFoundException {
|
|
super(calculatorName);
|
|
// Now check that it was one of our Kraskov-Grassberger calculators:
|
|
if (calculatorName.equalsIgnoreCase(COND_MI_CALCULATOR_KRASKOV1)) {
|
|
kraskovAlgorithmNumber = 1;
|
|
} else if (calculatorName.equalsIgnoreCase(COND_MI_CALCULATOR_KRASKOV2)) {
|
|
kraskovAlgorithmNumber = 2;
|
|
} else {
|
|
throw new ClassNotFoundException("Must be an underlying Kraskov-Grassberger conditional MI calculator");
|
|
}
|
|
props = new Hashtable<String,String>();
|
|
}
|
|
|
|
/* (non-Javadoc)
|
|
* @see infodynamics.measures.continuous.TransferEntropyCalculatorViaCondMutualInfo#initialise(int, int, int, int, int)
|
|
*/
|
|
@Override
|
|
public void initialise(int k, int k_tau, int l, int l_tau, int delay,
|
|
int[] condEmbedDims, int[] cond_taus, int[] condDelays)
|
|
throws Exception {
|
|
if (algChanged) {
|
|
// The algorithm number was changed in a setProperties call:
|
|
String newCalcName = COND_MI_CALCULATOR_KRASKOV1;
|
|
if (kraskovAlgorithmNumber == 2) {
|
|
newCalcName = COND_MI_CALCULATOR_KRASKOV2;
|
|
}
|
|
@SuppressWarnings("unchecked")
|
|
Class<ConditionalMutualInfoCalculatorMultiVariate> condMiClass =
|
|
(Class<ConditionalMutualInfoCalculatorMultiVariate>) Class.forName(newCalcName);
|
|
ConditionalMutualInfoCalculatorMultiVariate newCondMiCalc = condMiClass.newInstance();
|
|
construct(newCondMiCalc);
|
|
// Set the properties for the Kraskov MI calculators (may pass in properties for our super class
|
|
// as well, but they should be ignored)
|
|
for (String key : props.keySet()) {
|
|
newCondMiCalc.setProperty(key, props.get(key));
|
|
}
|
|
algChanged = false;
|
|
}
|
|
|
|
super.initialise(k, k_tau, l, l_tau, delay, condEmbedDims, cond_taus, condDelays);
|
|
}
|
|
|
|
/**
|
|
* 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 #PROP_KRASKOV_ALG_NUM} -- which Kraskov algorithm
|
|
* number to use (1 or 2). Will only be applied at the
|
|
* next initialisation.</li>
|
|
* <li>Any valid properties for {@link ConditionalTransferEntropyCalculatorViaCondMutualInfo#setProperty(String, String)}</li>
|
|
* <li>Any valid properties for {@link ConditionalMutualInfoCalculatorMultiVariateKraskov#setProperty(String, String)}</li>
|
|
* </ul>
|
|
* <p>One should set {@link ConditionalMutualInfoCalculatorMultiVariateKraskov#PROP_K} here, the number
|
|
* of neighbouring points one should count up to in determining the joint kernel size.</p>
|
|
*
|
|
* <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).
|
|
*/
|
|
@Override
|
|
public void setProperty(String propertyName, String propertyValue)
|
|
throws Exception {
|
|
if (propertyName.equalsIgnoreCase(PROP_KRASKOV_ALG_NUM)) {
|
|
int previousAlgNumber = kraskovAlgorithmNumber;
|
|
kraskovAlgorithmNumber = Integer.parseInt(propertyValue);
|
|
if ((kraskovAlgorithmNumber != 1) && (kraskovAlgorithmNumber != 2)) {
|
|
throw new Exception("Kraskov algorithm number (" + kraskovAlgorithmNumber
|
|
+ ") must be either 1 or 2");
|
|
}
|
|
if (kraskovAlgorithmNumber != previousAlgNumber) {
|
|
algChanged = true;
|
|
}
|
|
if (debug) {
|
|
System.out.println(this.getClass().getSimpleName() + ": Set property " + propertyName +
|
|
" to " + propertyValue);
|
|
}
|
|
} else {
|
|
// Assume it was a property for the parent class or underlying conditional MI calculator
|
|
super.setProperty(propertyName, propertyValue);
|
|
props.put(propertyName, propertyValue); // This will keep properties for the super class as well as the cond MI calculator, but this is ok
|
|
}
|
|
}
|
|
}
|