Source: animate.js

  1. define([
  2.     'underscore',
  3.     'trajectory'
  4. ],
  5. function(_, trajectory) {
  6.   var getSampleNamesAndDataForSortedTrajectories =
  7.     trajectory.getSampleNamesAndDataForSortedTrajectories;
  8.   var getMinimumDelta = trajectory.getMinimumDelta;
  9.   var TrajectoryOfSamples = trajectory.TrajectoryOfSamples;
  11.   /**
  12.    *
  13.    * @class AnimationDirector
  14.    *
  15.    * This object represents an animation director, as the name implies,
  16.    * is an object that manages an animation. Takes the for a plot (mapping file
  17.    * and coordinates) as well as the metadata categories we want to animate
  18.    * over.  This object gets called in the main emperor module when an
  19.    * animation starts and an instance will only be alive for one animation
  20.    * cycle i. e. until the cycle hits the final frame of the animation.
  21.    *
  22.    * @param {String[]} mappingFileHeaders an Array of strings containing
  23.    * metadata mapping file headers.
  24.    * @param {Object[]} mappingFileData an Array where the indices are sample
  25.    * identifiers and each of the contained elements is an Array of strings where
  26.    * the first element corresponds to the first data for the first column in the
  27.    * mapping file (mappingFileHeaders).
  28.    * @param {Object[]} coordinatesData an Array of Objects where the indices are
  29.    * the sample identifiers and each of the objects has the following
  30.    * properties: x, y, z, name, color, P1, P2, P3, ... PN where N is the number
  31.    * of dimensions in this dataset.
  32.    * @param {String} gradientCategory a string with the name of the mapping file
  33.    * header where the data that spreads the samples over a gradient is
  34.    * contained, usually time or days_since_epoch. Note that this should be an
  35.    * all numeric category.
  36.    * @param {String} trajectoryCategory a string with the name of the mapping
  37.    * file header where the data that groups the samples is contained, this will
  38.    * usually be BODY_SITE, HOST_SUBJECT_ID, etc..
  39.    * @param {speed} Positive real number determining the speed of an animation,
  40.    * this is reflected in the number of frames produced for each time interval.
  41.    *
  42.    * @return {AnimationDirector} returns an animation director if the parameters
  43.    * passed in were all valid.
  44.    *
  45.    * @throws {Error} Note that this class will raise an Error in any of the
  46.    * following cases:
  47.    * - One of the input arguments is undefined.
  48.    * - If gradientCategory is not in the mappingFileHeaders.
  49.    * - If trajectoryCategory is not in the mappingFileHeaders.
  50.    * @constructs AnimationDirector
  51.    */
  52.   function AnimationDirector(mappingFileHeaders, mappingFileData,
  53.                              coordinatesData, gradientCategory,
  54.                              trajectoryCategory, speed) {
  56.     // all arguments are required
  57.     if (mappingFileHeaders === undefined || mappingFileData === undefined ||
  58.       coordinatesData === undefined || gradientCategory === undefined ||
  59.       trajectoryCategory === undefined || speed === undefined) {
  60.       throw new Error('All arguments are required');
  61.     }
  63.     var index;
  65.     index = mappingFileHeaders.indexOf(gradientCategory);
  66.     if (index == -1) {
  67.       throw new Error('Could not find the gradient category in the mapping' +
  68.                       ' file');
  69.     }
  70.     index = mappingFileHeaders.indexOf(trajectoryCategory);
  71.     if (index == -1) {
  72.       throw new Error('Could not find the trajectory category in the mapping' +
  73.                       ' file');
  74.     }
  76.     // guard against logical problems with the trajectory object
  77.     if (speed <= 0) {
  78.       throw new Error('The animation speed cannot be less than or equal to ' +
  79.                       'zero');
  80.     }
  82.     /**
  83.      * @type {String[]}
  84.      mappingFileHeaders an Array of strings containing metadata mapping file
  85.      headers.
  86.      */
  87.     this.mappingFileHeaders = mappingFileHeaders;
  88.     /**
  89.      * @type {Object[]}
  90.      *an Array where the indices are sample identifiers
  91.      * and each of the contained elements is an Array of strings where the first
  92.      * element corresponds to the first data for the first column in the mapping
  93.      * file (mappingFileHeaders).
  94.      */
  95.     this.mappingFileData = mappingFileData;
  96.     /**
  97.      * @type {Object[]}
  98.      * an Array of Objects where the indices are the
  99.      * sample identifiers and each of the objects has the following properties:
  100.      * x, y, z, name, color, P1, P2, P3, ... PN where N is the number of
  101.      * dimensions in this dataset.
  102.      */
  103.     this.coordinatesData = coordinatesData;
  104.     /**
  105.      * @type {String}
  106.      *a string with the name of the mapping file
  107.      * header where the data that spreads the samples over a gradient is
  108.      * contained, usually time or days_since_epoch. Note that this should be an
  109.      * all numeric category
  110.      */
  111.     this.gradientCategory = gradientCategory;
  112.     /**
  113.      * @type {String}
  114.      * a string with the name of the mapping file
  115.      * header where the data that groups the samples is contained, this will
  116.      * usually be BODY_SITE, HOST_SUBJECT_ID, etc..
  117.      */
  118.     this.trajectoryCategory = trajectoryCategory;
  120.     /**
  121.      * @type {Float}
  122.      * A floating point value determining what the minimum separation between
  123.      * samples along the gradients is. Will be null until it is initialized to
  124.      * the values according to the input data.
  125.      * @default null
  126.      */
  127.     this.minimumDelta = null;
  128.     /**
  129.      * @type {Integer}
  130.      * Maximum length the groups of samples have along a gradient.
  131.      * @default null
  132.      */
  133.     this.maximumTrajectoryLength = null;
  134.     /*
  135.      * @type {Integer}
  136.      * The current frame being served by the director
  137.      * @default -1
  138.      */
  139.     this.currentFrame = -1;
  141.     /**
  142.      * @type {Integer}
  143.      * The previous frame served by the director
  144.      */
  145.     this.previousFrame = -1;
  147.     /**
  148.      * @type {Array}
  149.      * Array where each element in the trajectory is a trajectory with the
  150.      * interpolated points in it.
  151.      */
  152.     this.trajectories = [];
  154.     /**
  155.      * @type {Float}
  156.      * How fast should the animation run, has to be a postive non-zero value.
  157.      */
  158.     this.speed = speed;
  160.     this.initializeTrajectories();
  161.     this.getMaximumTrajectoryLength();
  163.     return this;
  164.   }
  166.   /**
  167.    *
  168.    * Initializes the trajectories that the director manages.
  169.    *
  170.    */
  171.   AnimationDirector.prototype.initializeTrajectories = function() {
  173.     var chewedData = null, trajectoryBuffer = null, minimumDelta;
  174.     var sampleNamesBuffer = [], gradientPointsBuffer = [];
  175.     var coordinatesBuffer = [];
  176.     var chewedDataBuffer = null;
  178.     // frames we want projected in the trajectory's interval
  179.     var n = Math.floor((1 / (this.speed)) * 10);
  181.     // compute a dictionary from where we will extract the germane data
  182.     chewedData = getSampleNamesAndDataForSortedTrajectories(
  183.         this.mappingFileHeaders, this.mappingFileData, this.coordinatesData,
  184.         this.trajectoryCategory, this.gradientCategory);
  186.     if (chewedData === null) {
  187.       throw new Error('Error initializing the trajectories, could not ' +
  188.                       'compute the data');
  189.     }
  191.     // calculate the minimum delta per step
  192.     this.minimumDelta = getMinimumDelta(chewedData);
  194.     // we have to iterate over the keys because chewedData is a dictionary-like
  195.     // object, if possible this should be changed in the future to be an Array
  196.     for (var key in chewedData) {
  198.       // re-initalize the arrays, essentially dropping all the previously
  199.       // existing information
  200.       sampleNamesBuffer = [];
  201.       gradientPointsBuffer = [];
  202.       coordinatesBuffer = [];
  204.       // buffer this to avoid the multiple look-ups below
  205.       chewedDataBuffer = chewedData[key];
  207.       // each of the keys is a trajectory name i. e. CONTROL, TREATMENT, etc
  208.       // we are going to generate buffers so we can initialize the trajectory
  209.       for (var index = 0; index < chewedDataBuffer.length; index++) {
  210.         // list of sample identifiers
  211.         sampleNamesBuffer.push(chewedDataBuffer[index]['name']);
  213.         // list of the value each sample has in the gradient
  214.         gradientPointsBuffer.push(chewedDataBuffer[index]['value']);
  216.         // x, y and z values for the coordinates data
  217.         coordinatesBuffer.push({'x': chewedDataBuffer[index]['x'],
  218.                                 'y': chewedDataBuffer[index]['y'],
  219.                                 'z': chewedDataBuffer[index]['z']});
  220.       }
  222.       // Don't add a trajectory unless it has more than one sample in the
  223.       // gradient. For example, there's no reason why we should animate a
  224.       // trajectory that has 3 samples at timepoint 0 ([0, 0, 0]) or a
  225.       // trajectory that has just one sample at timepoint 0 ([0])
  226.       if (sampleNamesBuffer.length <= 1 ||
  227.           _.uniq(gradientPointsBuffer).length <= 1) {
  228.         continue;
  229.       }
  231.       // create the trajectory object, we use Infinity to draw as many frames
  232.       // as they may be needed
  233.       trajectoryBuffer = new TrajectoryOfSamples(sampleNamesBuffer, key,
  234.           gradientPointsBuffer, coordinatesBuffer, this.minimumDelta, n,
  235.           Infinity);
  237.       this.trajectories.push(trajectoryBuffer);
  239.     }
  240.     return;
  241.   };
  243.   /**
  244.    *
  245.    * Retrieves the lengths of all the trajectories and figures out which of
  246.    * them is the longest one, then assigns that value to the
  247.    * maximumTrajectoryLength property.
  248.    * @return {Integer} Maximum trajectory length
  249.    *
  250.    */
  251.   AnimationDirector.prototype.getMaximumTrajectoryLength = function() {
  252.     if (this.maximumTrajectoryLength === null) {
  253.       this._computeN();
  254.     }
  256.     return this.maximumTrajectoryLength;
  257.   };
  259.   /**
  260.    *
  261.    * Helper function to compute the maximum length of the trajectories that the
  262.    * director is in charge of.
  263.    * @private
  264.    *
  265.    */
  266.   AnimationDirector.prototype._computeN = function() {
  267.     var arrayOfLengths = [];
  269.     // retrieve the length of all the trajectories
  270.     for (var index = 0; index < this.trajectories.length; index++) {
  271.       arrayOfLengths.push(
  272.           this.trajectories[index].interpolatedCoordinates.length);
  273.     }
  275.     // assign the value of the maximum value for these lengths
  276.     this.maximumTrajectoryLength = _.max(arrayOfLengths);
  277.   };
  279.   /**
  280.    *
  281.    * Helper method to update the value of the currentFrame property.
  282.    *
  283.    */
  284.   AnimationDirector.prototype.updateFrame = function() {
  285.     if (this.animationCycleFinished() === false) {
  286.       this.previousFrame = this.currentFrame;
  287.       this.currentFrame = this.currentFrame + 1;
  288.     }
  289.   };
  291.   /**
  292.    *
  293.    * Check whether or not the animation cycle has finished for this object.
  294.    * @return {bool} True if the animation has reached it's end and False if the
  295.    * animation still has frames to go.
  296.    *
  297.    */
  298.   AnimationDirector.prototype.animationCycleFinished = function() {
  299.     return this.currentFrame > this.getMaximumTrajectoryLength();
  300.   };
  302.   return AnimationDirector;
  303. });