update examples

README.md

+# OSHDB Examples
+
+These are some examples for the use of the OSHDB. This repository focusses on the [OSHDB-API](https://github.com/GIScience/oshdb/blob/master/documentation/oshdb-api-tutorial/README.md).
+
+You can checkout this repository an run the classes to see imediate results and try coding yourself.
+
+# Tutorial
+
+The [Tutorial](https://gitlab.gistools.geog.uni-heidelberg.de/giscience/big-data/ohsome/oshdb-examples/tree/master/src/main/java/org/heigit/bigspatialdata/oshdb/tutorial) is a quick and simple dive into the OSHDB-API-Code.
+
+# Analyses
+
+Some example analyses used in research are demonstrated in th [analyses](https://gitlab.gistools.geog.uni-heidelberg.de/giscience/big-data/ohsome/oshdb-examples/tree/master/src/main/java/org/heigit/bigspatialdata/oshdb/examples/analyses) package.

src/main/java/org/heigit/bigspatialdata/oshdb/examples/analyses/DistinctContributors.java

@@ -18,12 +18,17 @@ public class DistinctContributors {
         .getFile()
         .replace(".mv.db", "")))
         .multithreading(true);
-    OSHDBH2 oshdbKeytables = new OSHDBH2(DistinctContributors.class.getResource(
-        "/test.oshdb.keytables.mv.db").getFile().replace(".mv.db", ""));
+    
+    //keytables
+    OSHDBH2 oshdbKeytables = new OSHDBH2(
+        DistinctContributors.class.getResource("/test.oshdb.keytables.mv.db")
+            .getFile()
+            .replace(".mv.db", "")
+    );
+    
     // query
-
-    SortedMap<OSHDBTimestamp, Integer> result = OSMContributionView.on(oshdb).keytables(
-        oshdbKeytables)
+    SortedMap<OSHDBTimestamp, Integer> result = OSMContributionView.on(oshdb)
+        .keytables(oshdbKeytables)
         .areaOfInterest(new OSHDBBoundingBox(71.45, -1.16, 74.7, 7.47)) // maldives
         .timestamps("2007-01-01", "2017-12-01", Interval.MONTHLY)
         //.filter(k->k.is(ContributionType.CREATION) || k.is(ContributionType.DELETION )|| k.is(ContributionType.GEOMETRY_CHANGE)||k.is(ContributionType.TAG_CHANGE)||k.is(ContributionType.valueOf("")))

src/main/java/org/heigit/bigspatialdata/oshdb/examples/analyses/RoadLength.java

@@ -25,13 +25,17 @@ public class RoadLength {
 
   public static void main(String[] args) throws Exception {
     // database
-    OSHDBH2 oshdb = (new OSHDBH2(RoadLength.class.getResource("/test.oshdb.mv.db").getFile()
-        .replace(".mv.db", ""))).multithreading(true);
+    OSHDBH2 oshdb = (new OSHDBH2(RoadLength.class.getResource("/test.oshdb.mv.db")
+        .getFile()
+        .replace(".mv.db", "")))
+        .multithreading(true);
     OSHDBH2 oshdbKeytables = new OSHDBH2(RoadLength.class.getResource("/test.oshdb.keytables.mv.db")
-        .getFile().replace(".mv.db", ""));
+        .getFile()
+        .replace(".mv.db", ""));
+    
     // query
-    SortedMap<OSHDBTimestamp, Number> result = OSMEntitySnapshotView.on(oshdb).keytables(
-        oshdbKeytables)
+    SortedMap<OSHDBTimestamp, Number> result = OSMEntitySnapshotView.on(oshdb)
+        .keytables(oshdbKeytables)
         .areaOfInterest(new OSHDBBoundingBox(71.45, -1.16, 74.7, 7.47)) // maldives
         .timestamps("2007-01-01", "2017-12-01", Interval.MONTHLY)
         .osmType(OSMType.WAY)

src/main/java/org/heigit/bigspatialdata/oshdb/tutorial/AdvandcedExample.java

+package org.heigit.bigspatialdata.oshdb.tutorial;
+
+import java.sql.SQLException;
+import java.util.Arrays;
+import java.util.HashMap;
+import java.util.Map;
+import java.util.SortedMap;
+import org.heigit.bigspatialdata.oshdb.api.db.OSHDBDatabase;
+import org.heigit.bigspatialdata.oshdb.api.db.OSHDBH2;
+import org.heigit.bigspatialdata.oshdb.api.db.OSHDBJdbc;
+import org.heigit.bigspatialdata.oshdb.api.generic.function.SerializableBinaryOperator;
+import org.heigit.bigspatialdata.oshdb.api.generic.function.SerializableFunction;
+import org.heigit.bigspatialdata.oshdb.api.generic.function.SerializableSupplier;
+import org.heigit.bigspatialdata.oshdb.api.mapreducer.OSMContributionView;
+import org.heigit.bigspatialdata.oshdb.api.object.OSMContribution;
+import org.heigit.bigspatialdata.oshdb.osm.OSMType;
+import org.heigit.bigspatialdata.oshdb.util.OSHDBTimestamp;
+import org.heigit.bigspatialdata.oshdb.util.celliterator.ContributionType;
+import org.heigit.bigspatialdata.oshdb.util.time.OSHDBTimestamps;
+import org.jfree.ui.RefineryUtilities;
+
+public class AdvandcedExample {
+
+  public static void main(String[] args) 
+      throws SQLException, 
+      ClassNotFoundException, 
+      Exception {
+    
+    //Declare Database
+    OSHDBDatabase oshdb = new OSHDBH2(AdvandcedExample.class.getResource("/test.oshdb.mv.db")
+        .getFile()
+        .replace(".mv.db", ""));
+    OSHDBJdbc keytables = new OSHDBH2(Tutorial.class.getResource("/test.oshdb.keytables.mv.db")
+        .getFile()
+        .replace(".mv.db", ""));
+    
+    
+    //Define MapReducer
+    SortedMap<OSHDBTimestamp, Map<ContributionType, Integer>> reduce = OSMContributionView.on(oshdb)
+        .keytables(keytables)
+        .timestamps("2014-01-01", "2015-01-01", OSHDBTimestamps.Interval.MONTHLY)
+        .osmType(OSMType.WAY)
+        .osmTag("building")
+        .map(new Mapper())
+        .aggregateByTimestamp()
+        .reduce(new IdentitySupplier(), new Combiner());
+
+    //Display Result
+    TutorialChart chart = new TutorialChart("BigDB Analyses",
+        "Contribution-Types per timestamp!", reduce);
+    chart.pack();
+    RefineryUtilities.centerFrameOnScreen(chart);
+    chart.setVisible(true);
+  }
+
+  private static class Mapper implements
+      SerializableFunction<OSMContribution, Map<ContributionType, Integer>> {
+
+    @Override
+    public Map<ContributionType, Integer> apply(OSMContribution contribution) {
+      
+      //get an empty result-map
+      Map<ContributionType, Integer> result = new IdentitySupplier().get();
+      
+      //count contribution-types
+      contribution.getContributionTypes().forEach((ContributionType type) -> {
+        result.put(type, result.get(type) + 1);
+      });
+      return result;
+    }
+
+  }
+
+  private static class IdentitySupplier implements
+      SerializableSupplier<Map<ContributionType, Integer>> {
+
+    @Override
+    public Map<ContributionType, Integer> get() {
+      
+      //create an empty result-map
+      Map<ContributionType, Integer> result = new HashMap<>();
+      
+      //fill with 0 values
+      Arrays.asList(ContributionType.values())
+          .forEach(
+              (ContributionType type) ->
+              result.put(type, 0)
+          );
+      return result;
+    }
+
+  }
+
+  private static class Combiner implements
+      SerializableBinaryOperator<Map<ContributionType, Integer>> {
+
+    @Override
+    public Map<ContributionType, Integer> apply(
+        Map<ContributionType, Integer> mapResultA,
+        Map<ContributionType, Integer> mapResultB) {
+      
+      //get an empty result-map
+      Map<ContributionType, Integer> result = new IdentitySupplier().get();
+      
+      //put all counts of map-result A
+      result.putAll(mapResultA);
+      
+      //sum up with all result from map-result B
+      mapResultB.forEach((ContributionType cType, Integer integ) -> {
+        result.merge(cType, integ, (Integer int1, Integer int2) -> int1 + int2);
+      });
+
+      return result;
+    }
+
+  }
+
+}

src/main/java/org/heigit/bigspatialdata/oshdb/tutorial/README.md

+# Tutorial
+
+The basic tutorial is a realisation of the [OSHDB-API-Tutorial](https://github.com/GIScience/oshdb/blob/master/documentation/oshdb-api-tutorial/README.md). An alternative coding style can be found there. The code here tries to transparently demonstrate the intermediate steps of the process and transfers processing code to seperate classes that can easyly be extended.
+
+The advandced tutorial shows a more complex analysis.

src/main/java/org/heigit/bigspatialdata/oshdb/tutorial/Tutorial.java

@@ -2,151 +2,98 @@ package org.heigit.bigspatialdata.oshdb.tutorial;
 
 import java.io.IOException;
 import java.sql.SQLException;
-import java.util.SortedMap;
 import org.heigit.bigspatialdata.oshdb.api.db.OSHDBDatabase;
 import org.heigit.bigspatialdata.oshdb.api.db.OSHDBH2;
 import org.heigit.bigspatialdata.oshdb.api.db.OSHDBJdbc;
-import org.heigit.bigspatialdata.oshdb.api.generic.function.SerializableBiFunction;
-import org.heigit.bigspatialdata.oshdb.api.generic.function.SerializableBinaryOperator;
 import org.heigit.bigspatialdata.oshdb.api.generic.function.SerializableFunction;
 import org.heigit.bigspatialdata.oshdb.api.generic.function.SerializablePredicate;
-import org.heigit.bigspatialdata.oshdb.api.generic.function.SerializableSupplier;
-import org.heigit.bigspatialdata.oshdb.api.mapreducer.MapAggregator;
 import org.heigit.bigspatialdata.oshdb.api.mapreducer.MapReducer;
 import org.heigit.bigspatialdata.oshdb.api.mapreducer.OSMEntitySnapshotView;
 import org.heigit.bigspatialdata.oshdb.api.object.OSMEntitySnapshot;
-import org.heigit.bigspatialdata.oshdb.osm.OSMEntity;
 import org.heigit.bigspatialdata.oshdb.osm.OSMType;
 import org.heigit.bigspatialdata.oshdb.util.OSHDBBoundingBox;
-import org.heigit.bigspatialdata.oshdb.util.OSHDBTimestamp;
 import org.heigit.bigspatialdata.oshdb.util.geometry.Geo;
 import org.heigit.bigspatialdata.oshdb.util.time.OSHDBTimestamps.Interval;
-import org.jfree.ui.RefineryUtilities;
 
 public class Tutorial {
 
-  public static void main(String[] args) throws SQLException, ClassNotFoundException, IOException, Exception {
+  public static void main(String[] args) throws SQLException, ClassNotFoundException, IOException,
+      Exception {
 
     // -- PREPARATION --
-    // declare and open link to OSHDB
-    OSHDBDatabase oshdb = new OSHDBH2(Tutorial.class.getResource("/test.oshdb.mv.db").getFile().replace(".mv.db", ""));
-    // create MapReducer
+    // Start writing the OSHDB query
+    // declare and open a link to the OSHDB
+    OSHDBDatabase oshdb = new OSHDBH2(
+        Tutorial.class.getResource("/test.oshdb.mv.db")
+            .getFile()
+            .replace(".mv.db", "")
+    );
+
+    // Select OSHDB view
+    // create a MapReducer on Snapshots
     MapReducer<OSMEntitySnapshot> mapReducer = OSMEntitySnapshotView.on(oshdb);
 
     // -- MANDATORY SETTINGS --
-    // declare and open link to keytables
-    OSHDBJdbc tagsDB = new OSHDBH2(Tutorial.class.getResource("/test.oshdb.keytables.mv.db").getFile().replace(".mv.db", ""));
-    // add keytables to MapReducer
+    // declare and open a link to keytables
+    OSHDBJdbc tagsDB = new OSHDBH2(
+        Tutorial.class.getResource("/test.oshdb.keytables.mv.db")
+            .getFile()
+            .replace(".mv.db", "")
+    );
+    // add keytables to the MapReducer
     mapReducer = mapReducer.keytables(tagsDB);
 
+    // Setting spatial extent
     // create BoundingBox
-    OSHDBBoundingBox boundingBox = new OSHDBBoundingBox(71.45,-1.16,74.7,7.47);  //Maldives
-    // add bountingBox to MapReducer
+    OSHDBBoundingBox boundingBox = new OSHDBBoundingBox(71.45, -1.16, 74.7, 7.47);  //Maldives
+    // add hte boundingBox to the MapReducer
     mapReducer = mapReducer.areaOfInterest(boundingBox);
 
-    // add timestamps to MapReducer
+    //Setting temporal extent
+    // add timestamps of interest to the MapReducer
     mapReducer = mapReducer.timestamps("2014-01-01", "2015-01-01", Interval.MONTHLY);
 
-    // -- ENTITY FILTER --
+    // -- FILTER DATA --
     // by type
-    mapReducer = mapReducer.osmTypes(OSMType.WAY);
+    mapReducer = mapReducer.osmType(OSMType.WAY);
     // by tag
-    mapReducer = mapReducer.where("highway");
-    // by entity-definition
-    mapReducer = mapReducer.where(new EntityFilter());
+    mapReducer = mapReducer.osmTag("building");
 
-    // -- AGGREGATION --
-    // aggreate by timestamp into periods
-    MapAggregator<OSHDBTimestamp, OSMEntitySnapshot> mapAggregatorByTimestamp = mapReducer.aggregateByTimestamp();
+    // -- Calculating intermediate results --
+    // mapping snapshots to area-values using a seperate class
+    MapReducer<Double> mapReducerII = mapReducer.map(new Mapper());
 
-    // -- MAPPING --
-    // normal mapAggregatorTwoResultFilter 1->1
-    MapAggregator<OSHDBTimestamp, Double> mapAggregatorWithMap = mapAggregatorByTimestamp.map(new Mapper());
+    // -- Filtering intermediate results --
+    mapReducerII = mapReducerII.filter(new ResultFilter());
 
-    // -- RESULT FILTER --
-    mapAggregatorWithMap = mapAggregatorWithMap.filter(new ResultFilter());
-
-    // -- REPEAT --
-    MapAggregator<OSHDBTimestamp, Integer> mapAggregatorTwoResultFilter = mapAggregatorWithMap.map(new MapperII());
-    mapAggregatorTwoResultFilter.filter(new ResultFilterII());
-
-    // -- REDUCE --
-    // average
-    //SortedMap<OSHDBTimestamp, Double> average = mapAggregatorTwoResultFilter.average();
+    // -- Reqeusting aggregated result --
     // sum
-    //SortedMap<OSHDBTimestamp,Number> sum=mapAggregatorwithMap.sum();
-    // count
-    //SortedMap<OSHDBTimestamp,Integer> count=mapAggregatorwithMap.count();
-    // collect
-    //SortedMap<OSHDBTimestamp, List<Double>> collect = mapAggregatorwithMap.collect();
-    // unique
-    //SortedMap<OSHDBTimestamp, Set<Double>> uniq = mapAggregatorwithMap.uniq();
-    // traditional reduce
-    SortedMap<OSHDBTimestamp, Integer> result = mapAggregatorTwoResultFilter.reduce(new IdentitySupplier(), new Accumulator(), new Combiner());
+    Number result = mapReducerII.sum();
+
+    // --Tear Down --
+    oshdb.close();
+    tagsDB.close();
 
     // -- RESULT --
-    // how not to:
     System.out.println(result);
-
-    TutorialChart chart = new TutorialChart("BigDB Analyses", "Useless sum of some random statistics!", result);
-    chart.pack();
-    RefineryUtilities.centerFrameOnScreen(chart);
-    chart.setVisible(true);
-  }
-
-  private static class EntityFilter implements SerializablePredicate<OSMEntity> {
-    @Override
-    public boolean test(OSMEntity t) {
-      return t.getVersion() > 2;
-    }
   }
 
   private static class Mapper implements SerializableFunction<OSMEntitySnapshot, Double> {
-    @Override
-    public Double apply(OSMEntitySnapshot t) {
-      return Geo.lengthOf(t.getGeometry());
-    }
-  }
 
-  private static class ResultFilter implements SerializablePredicate<Double> {
     @Override
-    public boolean test(Double t) {
-      return t > 100.0;
+    public Double apply(OSMEntitySnapshot snapshot) {
+      return Geo.areaOf(snapshot.getGeometry());
     }
-  }
 
-  private static class MapperII implements SerializableFunction<Double, Integer> {
-    @Override
-    public Integer apply(Double t) {
-      return t.intValue();
-    }
   }
 
-  private static class ResultFilterII implements SerializablePredicate<Integer> {
-    @Override
-    public boolean test(Integer t) {
-      return (t % 2) == 0;
-    }
-  }
+  private static class ResultFilter implements SerializablePredicate<Double> {
 
-  private static class IdentitySupplier implements SerializableSupplier<Integer> {
     @Override
-    public Integer get() {
-      return 0;
+    public boolean test(Double area) {
+      return area < 1000.0;
     }
-  }
 
-  private static class Accumulator implements SerializableBiFunction<Integer, Integer, Integer> {
-    @Override
-    public Integer apply(Integer t, Integer u) {
-      return t + u;
-    }
   }
 
-  private static class Combiner implements SerializableBinaryOperator<Integer> {
-    @Override
-    public Integer apply(Integer t, Integer u) {
-      return t + u;
-    }
-  }
-}
\ No newline at end of file
+}

src/main/java/org/heigit/bigspatialdata/oshdb/tutorial/TutorialChart.java

 package org.heigit.bigspatialdata.oshdb.tutorial;
 
+import java.util.Arrays;
 import java.util.Iterator;
 import java.util.Map;
 import java.util.SortedMap;
 import org.heigit.bigspatialdata.oshdb.util.OSHDBTimestamp;
+import org.heigit.bigspatialdata.oshdb.util.celliterator.ContributionType;
 import org.jfree.chart.ChartFactory;
 import org.jfree.chart.ChartPanel;
 import org.jfree.chart.JFreeChart;
@@ -14,9 +16,12 @@ import org.jfree.ui.ApplicationFrame;
 
 public class TutorialChart extends ApplicationFrame {
 
-  private SortedMap<OSHDBTimestamp, Integer> dataset;
+  private SortedMap<OSHDBTimestamp, Map<ContributionType, Integer>> dataset;
 
-  public TutorialChart(String applicationTitle, String chartTitle, SortedMap<OSHDBTimestamp, Integer> result) {
+  public TutorialChart(
+      String applicationTitle, 
+      String chartTitle, 
+      SortedMap<OSHDBTimestamp, Map<ContributionType, Integer>> result) {
     super(applicationTitle);
     this.dataset = result;
     JFreeChart barChart = ChartFactory.createBarChart(
@@ -34,10 +39,15 @@ public class TutorialChart extends ApplicationFrame {
 
   private CategoryDataset createDataset() {
     DefaultCategoryDataset a = new DefaultCategoryDataset();
-    Iterator<Map.Entry<OSHDBTimestamp, Integer>> it = this.dataset.entrySet().iterator();
+    Iterator<Map.Entry<OSHDBTimestamp, Map<ContributionType, Integer>>> it = this.dataset.entrySet()
+        .iterator();
     while (it.hasNext()) {
-      Map.Entry<OSHDBTimestamp, Integer> ff = it.next();
-      a.addValue(ff.getValue(), ff.getKey(), "sum");
+      Map.Entry<OSHDBTimestamp, Map<ContributionType, Integer>> ff = it.next();
+      Arrays.asList(ContributionType.values()).forEach((ContributionType cType) -> {
+        a.addValue(ff.getValue().get(cType), cType, ff
+            .getKey());
+      });
+
     }
 
     return a;