Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Next revision
Previous revision
Last revision Both sides next revision
quickstart [2016/02/26 23:19]
a.leofreddi
quickstart [2019/08/10 16:17]
a.leofreddi
Line 1: Line 1:
 ====== Quickstart ====== ====== Quickstart ======
  
-Use the TimEL facade ​to compile and run a program:+To use TimEL you need to import the following dependecy:
  
-<code java+//Maven// 
-// Assemble the evaluation interval as [now, now + 1 second) +  ​<dependency
-long now = new Date().getTime();+      <​groupId>​net.vleo.timel<​/groupId>​ 
 +      <​artifactId>​timel-core<​/artifactId>​ 
 +      <​version>​0.9.2</​version>​ 
 +  </​dependency>​
  
-Interval interval = Interval.of(now, now + 1000L);+//​Gradle//​ 
 +  implementation 'net.vleo.timel:​timel-core:​0.9.2'​
  
-// Compile the expression 1 + 1 +\\
-Expression<​Double>​ expression = TimEL +
-    .getCompiler("​1 + 1") // Get the compiler builder for the expression 1+1 +
-    .compileExpression(Types.getNumericDoubleType());​ // Compile the source as an expression  +
-                                                      // that returns a double+
  
-// Execute the expression +Now you're ready to go! Let's count how many days passed since (unixepoch:
-TimeIterator<​Double>​ itor = TimEL +
-    .getExecutor(expression// Get executor for the expression +
-    .evaluateFor(interval);​ // Evaluate for the given interval+
  
-// Since 1+is constant we'll have a single sample for the whole interval +<code java> 
-double v itor.next().getValue();+// Compile the expression 
 +Expression<?>​ expression = TimEL 
 +        .parse("​scale(scale(uniform(1.0), every(1, \"​DAY_OF_YEAR\",​ \"​UTC\"​)))"​) 
 +        .compile();​ 
 + 
 +// Evaluate and print the number of days from epoch 
 +Interval interval ​Interval.of(Instant.ofEpochMilli(0), Instant.now()); 
 +System.out.println(TimEL.evaluate(expression,​ interval).next());
 </​code>​ </​code>​
  
-Note that all the job is done through the TimEL facade, first compiling the expression and then executing it.+===== Adding a variable =====
  
-The following example shows how to provide ​non constant values to TimEL using *variable*+Now let's try something a bit more complex, where we provide ​an input time-serie variable. As TimEL is streaming api, it will pull values out of the variable ​when it needs themIn this case we are going to use a TreeMapVariable,​ which is a Variable backed by a regular in memory TreeMap:
  
 <code java> <code java>
-TreeMapVariable<​Double> variable = new TreeMapVariable<​Double>(); +// Create a new variable backed by a TreeMap 
- +TreeMapVariable<​Integer> variable = new TreeMapVariable<>​();​ 
-long now = new Date().getTime();​ +TreeMap<​Interval, ​Integer> values = variable.getTreeMap();
- +
-// Retrieve the map backing the TreeMapVariable +
-TreeMap<​Interval, ​Double> values = variable.getBackMap();+
  
 // Add some values to the variable // Add some values to the variable
-values.put(Interval.of(now,​ now + 1000), 1.0); // [nownow + 1s) = 1.0 +Instant now = Instant.now(); 
-values.put(Interval.of(now + 1000now + 2000), 2.0); // [now + 1snow + 2s= 2.0 +for(int[] i : new int[][] { 
-values.put(Interval.of(now ​+ 2000now + 3000), 3.0); // [now + 2snow + 3s= 3.0+        ​// start, end, value 
 +        {0, 1, 1}, 
 +        {12, 2}, 
 +        ​// gap between 2nd and 3rd minute 
 +        {3, 44} 
 + }{ 
 +    values.put(Interval.of( 
 +            ​now.plus(i[0]ChronoUnit.MINUTES), 
 +            now.plus(i[1]ChronoUnit.MINUTES) 
 +    ), i[2]); 
 +}
  
-// Compile ​the A A expression +// Compile ​"​a ​a" without type requirement 
-Expression<​Double> expression = TimEL +Expression<​?> expression = TimEL 
-        .getCompiler("A") +        .parse("a") 
-        .declareVariable("A", ​Types.getNumericDoubleType()) // Declare ​as a numeric type +        .withVariable("a", ​new IntegerType(), variable) // Declare ​'​a' ​as a int 
-        .compileExpression(Types.getNumericDoubleType()); // Expect a numeric result+        .compile();
  
-// Evaluate the expression in the interval [now, now + 3 seconds+// Evaluate the expression in the interval [now, now + 5 minutes
-TimeIterator<​Double> itor = TimEL +TimeIterator<​?> itor = TimEL 
-        .getExecutor(expression+        .evaluate(expression,​ Interval.of(now,​ now.plus(5, ChronoUnit.MINUTES)));
-        .bindVariable("​A"​variable) +
-        .evaluateFor(Interval.of(now,​ now + 3000));+
  
-System.out.println("​Starting evaluation..."​);​ +// Pull the results, effectively evaluating ​the expression. 
- +// This will print 3 lines, one for each interval, with the value 1, 4 and 16.
-// Now trigger ​the evaluation reading ​the output +
-// +
-// This will print 3 lines, one for each interval, +
-// with the value 1, 4 and 9.+
 while(itor.hasNext()) while(itor.hasNext())
-    System.out.println(itor.next());​+    System.out.println("​\t"​ + itor.next());​
 </​code>​ </​code>​
  
-Note that TimEL works in a streaming way, that is it pulls values from input and computes the result as soon as the output iterator is advanced. This way allows the library to work incrementally,​ thus the whole dataset is not required to fit in memory (imagine having various year of samples at a second resolution!) but can be instead streamed when needed. +That'​s ​it!
- +
-To provide values to a TimEL program or expression the followings steps are needed, as shown above: +
- +
-  - The variable needs to be declared at compile time with its relative type; +
-  - An instance of the variable needs to be bounded at execution time. +
- +
-TimEL is agnostic to data storage and requires the user to implement the **Variable** interface to allow read and write operations. Note that reading an interval in both directions is required. +
- +
-The commodity **TreeMapVariable** class is a **Variable** implementation backed by a TreeMap can be used when the dataset is not large. +
- +
-===== Stability ===== +
- +
-**Please consider the API not mature yet and subject to change**. Although no major changes are expected in the TimEL facade, the type mechanism is still prototypal an might be subject to changes. +
- +
-Anything in the impl package is to be considered private, and therefore, unstable.+
  
  
  
  • quickstart.txt
  • Last modified: 2019/10/31 19:30
  • by a.leofreddi