Merge pull request #28 from BauhausLuftfahrt/javaDocUpdate

Java doc update
BauhausLuftfahrt · Sep 24, 2019 · 0ea0852 · 0ea0852
2 parents ce93e42 + 3a75180
commit 0ea0852
Show file tree

Hide file tree

Showing 191 changed files with 2,412 additions and 1,273 deletions.
diff --git a/src/main/java/net/bhl/matsim/uam/analysis/RunBatchConversions.java b/src/main/java/net/bhl/matsim/uam/analysis/RunBatchConversions.java
@@ -7,8 +7,20 @@
 import net.bhl.matsim.uam.analysis.trips.run.BatchConvertTripsFromEvents;
 import net.bhl.matsim.uam.analysis.trips.run.BatchConvertTripsFromPopulation;
 import net.bhl.matsim.uam.analysis.uamdemand.run.BatchConvertUAMDemandFromEvents;
+import net.bhl.matsim.uam.analysis.uamdemand.run.ConvertUAMDemandFromEvents;
 import net.bhl.matsim.uam.analysis.uamstations.run.BatchConvertUAMStationsFromUAMVehicles;
 
+/**
+ * This script takes a specific folder path and runs
+ * {@link BatchConvertUAMStationsFromUAMVehicles},
+ * {@link BatchConvertUAMDemandFromEvents}, {@link BatchConvertTripsFromEvents},
+ * {@link BatchConvertTransitTripsFromEvents},
+ * {@link BatchConvertTripsFromPopulation} and
+ * {@link BatchConvertLinkStatsFromEvents} consecutively for all MATSim output
+ * folders within the provided base folder.
+ * 
+ * @author balacmi (Milos Balac), RRothfeld (Raoul Rothfeld)
+ */
 public class RunBatchConversions {
 
 	public static void main(String[] args) throws IOException {

diff --git a/...main/java/net/bhl/matsim/uam/analysis/demographics/ConvertDemographicsFromPopulation.java b/...main/java/net/bhl/matsim/uam/analysis/demographics/ConvertDemographicsFromPopulation.java
@@ -22,10 +22,18 @@
 import org.matsim.households.Household;
 import org.matsim.households.HouseholdsReaderV10;
 
+/**
+ * This script Creates a demographics file by reading through and gathering
+ * socio-demographic attributes from each person object in an existing
+ * population (or plan) file. Necessary inputs are in the following order:
+ * -plans file; -households file; -output file
+ * 
+ * @author balacmi (Milos Balac), RRothfeld (Raoul Rothfeld)
+ */
 public class ConvertDemographicsFromPopulation {
 
 	public static void main(String[] args) throws IOException {
-		//cmd-line input: input-population input-households outfile
+		// cmd-line input: input-population input-households outfile
 		Scenario scenario = ScenarioUtils.createScenario(ConfigUtils.createConfig());
 
 		int i = 0;
@@ -37,93 +45,93 @@ public static void main(String[] args) throws IOException {
 		for (Household household : scenario.getHouseholds().getHouseholds().values()) {
 			household.getMemberIds().forEach(id -> householdMap.put(id, household.getId()));
 		}
-		
+
 		Set<String> columns = new HashSet<String>();
 		Set<Map<String, String>> population = new HashSet<Map<String, String>>();
 		for (Person person : scenario.getPopulation().getPersons().values()) {
 			Map<String, String> personAttrMap = new HashMap<String, String>();
-			
+
 			personAttrMap.put("ID", person.getId().toString());
 			columns.add("ID");
-			
-			String[] attributePairs = person.getAttributes().toString().split("[{}]+");			
+
+			String[] attributePairs = person.getAttributes().toString().split("[{}]+");
 			for (String attributePair : attributePairs) {
 				if (attributePair.isEmpty())
 					continue;
-				
+
 				String[] extracts = attributePair.split("[;=]+");
 				// e.g. key age object 39
 				columns.add(extracts[1].trim());
 				personAttrMap.put(extracts[1].trim(), extracts[3].trim());
 			}
-			
+
 			Household household = scenario.getHouseholds().getHouseholds().get(householdMap.get(person.getId()));
-			
+
 			if (household != null) {
 				personAttrMap.put("household_ID", household.getId().toString());
 				columns.add("household_ID");
-				
+
 				personAttrMap.put("household_income", "" + household.getIncome().getIncome());
 				columns.add("household_income");
-				
+
 				personAttrMap.put("household_currency", household.getIncome().getCurrency());
 				columns.add("household_currency");
-				
+
 				personAttrMap.put("household_incomePeriod", household.getIncome().getIncomePeriod().toString());
 				columns.add("household_incomePeriod");
 
-				String[] hhAttributePairs = household.getAttributes().toString().split("[{}]+");			
+				String[] hhAttributePairs = household.getAttributes().toString().split("[{}]+");
 				for (String hhAttributePair : hhAttributePairs) {
 					if (hhAttributePair.isEmpty())
 						continue;
-					
+
 					String[] extracts = hhAttributePair.split("[;=]+");
 					// e.g. key age object 39
 					columns.add("household_" + extracts[1].trim());
 					personAttrMap.put("household_" + extracts[1].trim(), extracts[3].trim());
 				}
 			}
-			
+
 			population.add(personAttrMap);
 		}
-		
+
 		BufferedWriter writer = new BufferedWriter(new OutputStreamWriter(new FileOutputStream(outfile)));
-		
+
 		// Make columns into ordered list, write header
 		List<String> columnList = new ArrayList<String>();
 		columnList.addAll(columns);
 		Collections.sort(columnList);
 		System.out.println(columnList);
-		
+
 		boolean first = true;
 		for (Map<String, String> personAttrMap : population) {
 			if (first) {
 				first = false;
-				
+
 				for (Iterator<String> it = columnList.iterator(); it.hasNext();) {
-				    writer.write(it.next());
-				    
-				    if (it.hasNext())
-				    	writer.write(",");
-				    else
-				    	writer.write(System.lineSeparator());
+					writer.write(it.next());
+
+					if (it.hasNext())
+						writer.write(",");
+					else
+						writer.write(System.lineSeparator());
 				}
 			}
-			
+
 			for (Iterator<String> it = columnList.iterator(); it.hasNext();) {
 				String key = it.next();
 				if (personAttrMap.containsKey(key))
 					writer.write(personAttrMap.get(key));
-			    
-			    if (it.hasNext())
-			    	writer.write(",");
-			    else
-			    	writer.write(System.lineSeparator());
+
+				if (it.hasNext())
+					writer.write(",");
+				else
+					writer.write(System.lineSeparator());
 			}
 		}
-		
+
 		writer.close();
-		
+
 		System.out.println("done.");
 	}
 }
diff --git a/src/main/java/net/bhl/matsim/uam/analysis/traffic/CSVLinkStatsWriter.java b/src/main/java/net/bhl/matsim/uam/analysis/traffic/CSVLinkStatsWriter.java
@@ -10,6 +10,12 @@
 import java.util.SortedSet;
 import java.util.TreeSet;
 
+/**
+ * This class writes a CSV file containing information of links for different
+ * times.
+ * 
+ * @author balacmi (Milos Balac), RRothfeld (Raoul Rothfeld)
+ */
 public class CSVLinkStatsWriter {
 	final private Collection<LinkStatsItem> links;
 	final private String delimiter;
@@ -38,7 +44,7 @@ private String formatHeader() {
 		header.add("link_id");
 		header.add("length_m");
 		header.add("freespeed_ms");
-		
+
 		timeHeaders = new TreeSet<Integer>();
 		for (LinkStatsItem link : links) {
 			for (Integer i : link.timeDependantSpeed.keySet()) {
@@ -47,7 +53,7 @@ private String formatHeader() {
 		}
 
 		for (Integer timeHead : timeHeaders) {
-			header.add("avgspeed_ms_at_H" + (int) (timeHead/ 3600) + "M" + (int) ((timeHead % 3600) / 60));
+			header.add("avgspeed_ms_at_H" + (int) (timeHead / 3600) + "M" + (int) ((timeHead % 3600) / 60));
 		}
 
 		return String.join(delimiter, header);
@@ -58,7 +64,7 @@ private String formatLinkStatsItem(LinkStatsItem link) {
 		row.add(link.linkId.toString());
 		row.add(String.valueOf(link.distance));
 		row.add(String.valueOf(link.freeSpeed));
-		
+
 		for (Integer timeHead : timeHeaders) {
 			if (link.timeDependantSpeed.containsKey(timeHead))
 				row.add(String.valueOf(link.timeDependantSpeed.get(timeHead)));

diff --git a/src/main/java/net/bhl/matsim/uam/analysis/traffic/LinkStatsItem.java b/src/main/java/net/bhl/matsim/uam/analysis/traffic/LinkStatsItem.java
@@ -7,6 +7,11 @@
 import org.matsim.api.core.v01.network.Link;
 import org.matsim.api.core.v01.population.Person;
 
+/**
+ * This class stores link information in a specific time.
+ * 
+ * @author balacmi (Milos Balac), RRothfeld (Raoul Rothfeld)
+ */
 public class LinkStatsItem {
 	public Id<Link> linkId;
 	public double distance;

diff --git a/src/main/java/net/bhl/matsim/uam/analysis/traffic/run/BatchConvertLinkStatsFromEvents.java b/src/main/java/net/bhl/matsim/uam/analysis/traffic/run/BatchConvertLinkStatsFromEvents.java
@@ -1,13 +1,21 @@
 package net.bhl.matsim.uam.analysis.traffic.run;
 
 import java.io.File;
+
 import java.io.IOException;
 import java.nio.file.Paths;
 import java.util.Collection;
 import java.util.HashSet;
 
 import org.apache.commons.io.FileUtils;
 
+/**
+ * This script takes a specific folder path and runs
+ * {@link ConvertLinkStatsFromEvents} for all all MATSim output folders within
+ * the provided base folder.
+ * 
+ * @author balacmi (Milos Balac), RRothfeld (Raoul Rothfeld)
+ */
 public class BatchConvertLinkStatsFromEvents {
 	// PROVIDE PARENT FOLDER OF OUTPUT FOLDERS
 	private static String eventfile = "output_events.xml";

diff --git a/src/main/java/net/bhl/matsim/uam/analysis/traffic/run/ConvertLinkStatsFromEvents.java b/src/main/java/net/bhl/matsim/uam/analysis/traffic/run/ConvertLinkStatsFromEvents.java
@@ -6,7 +6,6 @@
 import java.util.HashMap;
 import java.util.HashSet;
 import java.util.Map;
-import java.util.Set;
 
 import org.matsim.api.core.v01.network.Link;
 import org.matsim.api.core.v01.network.Network;
@@ -15,21 +14,20 @@
 import org.matsim.core.events.EventsReaderXMLv1;
 import org.matsim.core.events.EventsUtils;
 import org.matsim.core.network.NetworkUtils;
-import org.matsim.core.network.algorithms.TransportModeNetworkFilter;
 import org.matsim.core.network.io.MatsimNetworkReader;
 import org.matsim.core.trafficmonitoring.TravelTimeCalculator;
 
 import net.bhl.matsim.uam.analysis.traffic.CSVLinkStatsWriter;
 import net.bhl.matsim.uam.analysis.traffic.LinkStatsItem;
 
 /**
-* This script generates a csv file containing the average speed per link per hour of the input network from an output simulation events file.
-* trips performed from an events output file.
-* Necessary inputs are in the following order:
-* -Network file;
-* -Events file;
-* -output file;
-*/
+ * This script generates a csv file containing the average speed per link per
+ * hour of the input network from an output simulation events file. trips
+ * performed from an events output file. Necessary inputs are in the following
+ * order: -Network file; -Events file; -output file;
+ * 
+ * @author balacmi (Milos Balac), RRothfeld (Raoul Rothfeld)
+ */
 public class ConvertLinkStatsFromEvents {
 
 	static int timeBinSize = 3600;
@@ -48,34 +46,31 @@ static public void main(String[] args) throws IOException {
 	static public void extract(String network, String events, String outfile) throws IOException {
 		Network netw = NetworkUtils.createNetwork();
 		new MatsimNetworkReader(netw).readFile(network);
-		
+
 		TravelTimeCalculatorConfigGroup tconfig = new TravelTimeCalculatorConfigGroup();
-		tconfig.setAnalyzedModes(analyzedMode);  // TODO does nothing?
+		tconfig.setAnalyzedModes(analyzedMode); // TODO does nothing?
 		tconfig.setCalculateLinkToLinkTravelTimes(calculateLinkToLinkTravelTimes);
 		tconfig.setCalculateLinkTravelTimes(calculateLinkTravelTimes);
 		tconfig.setFilterModes(filterModes); // TODO does nothing?
 		tconfig.setMaxTime(maxTime);
 		tconfig.setTraveltimeBinSize(timeBinSize);
-		
+
 		TravelTimeCalculator ttc = TravelTimeCalculator.create(netw, tconfig);
-        EventsManager manager = EventsUtils.createEventsManager();
+		EventsManager manager = EventsUtils.createEventsManager();
 		manager.addHandler(ttc);
-        EventsReaderXMLv1 eventsReader = new EventsReaderXMLv1(manager);
-        eventsReader.readFile(events);
-
-        Collection<LinkStatsItem> linkStats = new HashSet<>();
-        for (Link link : netw.getLinks().values()) {
-        	Map<Integer, Double> timeDependantSpeeds = new HashMap<>();
-        	for (int time = 0 + timeBinSize / 2; time < maxTime; time += timeBinSize) {
-        		timeDependantSpeeds.put(time, link.getLength() / ttc.getLinkTravelTime(link, time));
-        	}
-
-    		linkStats.add(new LinkStatsItem(link.getId(),
-    				link.getLength(),
-    				link.getFreespeed(),
-    				timeDependantSpeeds));
-        }
-
-        new CSVLinkStatsWriter(linkStats).write(outfile);
+		EventsReaderXMLv1 eventsReader = new EventsReaderXMLv1(manager);
+		eventsReader.readFile(events);
+
+		Collection<LinkStatsItem> linkStats = new HashSet<>();
+		for (Link link : netw.getLinks().values()) {
+			Map<Integer, Double> timeDependantSpeeds = new HashMap<>();
+			for (int time = 0 + timeBinSize / 2; time < maxTime; time += timeBinSize) {
+				timeDependantSpeeds.put(time, link.getLength() / ttc.getLinkTravelTime(link, time));
+			}
+
+			linkStats.add(new LinkStatsItem(link.getId(), link.getLength(), link.getFreespeed(), timeDependantSpeeds));
+		}
+
+		new CSVLinkStatsWriter(linkStats).write(outfile);
 	}
 }
diff --git a/src/main/java/net/bhl/matsim/uam/analysis/transit/CSVTransitTripWriter.java b/src/main/java/net/bhl/matsim/uam/analysis/transit/CSVTransitTripWriter.java
@@ -6,6 +6,12 @@
 import java.io.OutputStreamWriter;
 import java.util.Collection;
 
+/**
+ * This class writes a CSV file containing information about trips performed by
+ * transit.
+ * 
+ * @author balacmi (Milos Balac), RRothfeld (Raoul Rothfeld)
+ */
 public class CSVTransitTripWriter {
 	final private Collection<TransitTripItem> trips;
 	final private String delimiter;
@@ -43,13 +49,15 @@ private String formatHeader() {
 	}
 
 	private String formatTrip(TransitTripItem trip) {
-		return String.join(delimiter, new String[] { trip.personId.toString(), String.valueOf(trip.personTripId),
-				String.valueOf(trip.origin.getX()), String.valueOf(trip.origin.getY()),
-				String.valueOf(trip.destination.getX()), String.valueOf(trip.destination.getY()),
-				String.valueOf(trip.startTime), String.valueOf(trip.inVehicleTime), String.valueOf(trip.waitingTime),
-				String.valueOf(trip.transferTime), String.valueOf(trip.inVehicleDistance),
-				String.valueOf(trip.inVehicleCrowflyDistance), String.valueOf(trip.transferDistance),
-				String.valueOf(trip.transferCrowflyDistance), String.valueOf(trip.numberOfTransfers),
-				String.valueOf(trip.crowflyDistance), String.valueOf(trip.firstWaitingTime), String.valueOf(trip.routing) });
+		return String.join(delimiter,
+				new String[] { trip.personId.toString(), String.valueOf(trip.personTripId),
+						String.valueOf(trip.origin.getX()), String.valueOf(trip.origin.getY()),
+						String.valueOf(trip.destination.getX()), String.valueOf(trip.destination.getY()),
+						String.valueOf(trip.startTime), String.valueOf(trip.inVehicleTime),
+						String.valueOf(trip.waitingTime), String.valueOf(trip.transferTime),
+						String.valueOf(trip.inVehicleDistance), String.valueOf(trip.inVehicleCrowflyDistance),
+						String.valueOf(trip.transferDistance), String.valueOf(trip.transferCrowflyDistance),
+						String.valueOf(trip.numberOfTransfers), String.valueOf(trip.crowflyDistance),
+						String.valueOf(trip.firstWaitingTime), String.valueOf(trip.routing) });
 	}
 }
diff --git a/src/main/java/net/bhl/matsim/uam/analysis/transit/TransitTripItem.java b/src/main/java/net/bhl/matsim/uam/analysis/transit/TransitTripItem.java
@@ -4,6 +4,11 @@
 import org.matsim.api.core.v01.Id;
 import org.matsim.api.core.v01.population.Person;
 
+/**
+ * This class stores information about a trip performed by transit.
+ * 
+ * @author balacmi (Milos Balac), RRothfeld (Raoul Rothfeld)
+ */
 public class TransitTripItem {
 	public Id<Person> personId = null;
 	public int personTripId = -1;
@@ -25,7 +30,7 @@ public class TransitTripItem {
 	public double transferCrowflyDistance = 0.0;
 
 	public int numberOfTransfers = -1;
-	
+
 	public String routing = "";
 
 	public double firstWaitingTime = Double.NaN;

diff --git a/src/main/java/net/bhl/matsim/uam/analysis/transit/listeners/TransitTripListener.java b/src/main/java/net/bhl/matsim/uam/analysis/transit/listeners/TransitTripListener.java
@@ -30,6 +30,11 @@
 import ch.ethz.matsim.baseline_scenario.transit.events.PublicTransitEvent;
 import net.bhl.matsim.uam.analysis.transit.TransitTripItem;
 
+/**
+ * A listener that retrieves information from transit events.
+ * 
+ * @author balacmi (Milos Balac), RRothfeld (Raoul Rothfeld)
+ */
 public class TransitTripListener
 		implements ActivityStartEventHandler, ActivityEndEventHandler, PersonDepartureEventHandler,
 		PersonArrivalEventHandler, GenericEventHandler, TeleportationArrivalEventHandler, PersonStuckEventHandler {