Review error messages and tests. Refine demo models.

Author: chrfrantz

demo/dbscan-clustering-demo-v5.nlogo

@@ -219,7 +219,7 @@ HORIZONTAL
 @#$#@#$#@
 ## WHAT IS IT?
 
-This model demonstrates the use of the DBSCAN extension (https://github.com/chrfrantz/NetLogo-Extension-DBSCAN/). It highlights clustering of individuals/turtles by both variables as well as location.
+This model demonstrates the use of the DBSCAN extension (https://github.com/chrfrantz/NetLogo-Extension-DBSCAN/). It highlights clustering of individuals/turtles by both variables as well as location. (Clustering of patches is supported for NetLogo 6 onwards.)
 
 ## HOW IT WORKS
 
@@ -237,7 +237,7 @@ Click either button and observe how the clustering works both for variable-based
 
 ## THINGS TO TRY
 
-Try varying the maximum distance (slider 'max-distance-agents') to see how agents are clustered by variable for different wealth ranges (button 'cluster-agents-by-variable').  The same slider is also used for the maximum permissible distance between agents if performing location-based clustering (button 'cluster-agents-by-location'). You can further vary the number of members necessary to form a cluster and see how this changes the emerging clusters.
+Try varying the maximum distance (slider 'maximum-distance-agents') to see how agents are clustered by variable for different wealth ranges (button 'cluster-agents-by-variable').  The same slider is also used for the maximum permissible distance between agents if performing location-based clustering (button 'cluster-agents-by-location'). You can further vary the number of members necessary to form a cluster (slider 'minimum-number-of-members') and see how this changes the emerging clusters.
 
 ## NETLOGO FEATURES
 

demo/dbscan-clustering-demo-v6.nlogo

@@ -4,9 +4,9 @@
 ;
 ; Author: Christopher Frantz ([email protected])
 ;
-; Last update: 29/05/2019
+; Last update: 30/05/2019
 ;
-; For documentation and details about supported NetLogo versions refer to
+; For documentation and details about the extension and supported NetLogo versions refer to
 ; https://github.com/chrfrantz/NetLogo-Extension-DBSCAN#readme
 ;
 
@@ -304,7 +304,7 @@ Click either button and observe how the clustering works both for variable-based
 
 ## THINGS TO TRY
 
-Try varying the maximum distance (slider 'max-distance-agents') to see how agents are clustered by variable for different wealth ranges (button 'cluster-agents-by-variable').  The same slider is also used for the maximum permissible distance between agents if performing location-based clustering (button 'cluster-agents-by-location'). In addition, try out the clustering of patches by different resource levels (slider 'max-distance-patches') using the button 'cluster-patches-by-variable'. You can further vary the number of members (i.e., agents or patches) necessary to form a cluster and see how this changes the emerging clusters.
+Try varying the maximum distance (slider 'maximum-distance-agents') to see how agents are clustered by variable for different wealth ranges (button 'cluster-agents-by-variable').  The same slider is also used for the maximum permissible distance between agents if performing location-based clustering (button 'cluster-agents-by-location'). In addition, try out the clustering of patches by different resource levels (slider 'maximum-distance-patches') using the button 'cluster-patches-by-variable'. You can further vary the number of members (i.e., agents or patches) necessary to form a cluster (slider 'minimum-number-of-members') and see how this changes the emerging clusters.
 
 ## NETLOGO FEATURES
 

res/README.txt

@@ -1,4 +1,4 @@
-This archive contains the DBSCAN Extension for NetLogo, v0.3 (28.05.2019). 
+This archive contains the DBSCAN Extension for NetLogo, v0.3 (30.05.2019). 
 
 Note: The new feature of this release (clustering patches - as opposed to just
 turtles - by variable) are only supported for NetLogo versions 6 and higher.

src/main/java/org/nlogo/extensions/dbscan/DBSCANExtension.java

@@ -27,8 +27,10 @@
 /**
  * NetLogo extension for clustering based on DBSCAN by agent/patch variables or coordinates.
  * 
+ * Website: https://github.com/chrfrantz/NetLogo-Extension-DBSCAN
+ * 
  * @author <a href="mailto:[email protected]>Christopher Frantz</a>
- * @version 0.3 (28.05.2019)
+ * @version 0.3 (30.05.2019)
  *
  */
 public class DBSCANExtension extends DefaultClassManager {
@@ -60,8 +62,8 @@ public Object report(final Argument[] args, final Context ctx)
 
             AgentSet inputValues = null;
             String field = null;
-            int minNumberOfElements = -1;
-            double maxDistance = -1;
+            int minNumberOfElements = -9999;
+            double maxDistance = -9999;
 
             try {
                 inputValues = args[0].getAgentSet();
@@ -71,26 +73,34 @@ public Object report(final Argument[] args, final Context ctx)
             } catch (Exception e) {
                 throw new ExtensionException(e.getMessage());
             }
-            
+
             if (inputValues == null || inputValues.isEmpty()) {
                 throw new ExtensionException(DBSCANExtensionErrors.ERROR_MISSING_INPUT_DATA);
             }
 
             if (field == null || field.isEmpty()) {
                 throw new ExtensionException(DBSCANExtensionErrors.ERROR_MISSING_CLUSTER_VARIABLE);
             }
-            
-            if (minNumberOfElements == -1) {
+
+            if (minNumberOfElements == -9999) {
                 throw new ExtensionException(DBSCANExtensionErrors.ERROR_MISSING_MINIMUM_NUMBER_OF_ELEMENTS);
             }
 
-            if (maxDistance == -1) {
+            if (minNumberOfElements <= 1) {
+                throw new ExtensionException(DBSCANExtensionErrors.ERROR_INVALID_MINIMUM_NUMBER_OF_ELEMENTS);
+            }
+
+            if (maxDistance == -9999) {
                 throw new ExtensionException(DBSCANExtensionErrors.ERROR_MISSING_MAXIMUM_DISTANCE_OF_ELEMENTS);
             }
 
+            if (maxDistance < 0) {
+                throw new ExtensionException(DBSCANExtensionErrors.ERROR_NEGATIVE_MAXIMUM_DISTANCE_OF_ELEMENTS);
+            }
+
             // Convert input AgentSet to Collection
             Iterator<?> it = inputValues.agents().iterator();
-            
+
             // Check for patches
             boolean patches = false;
             int fieldIndex = -1;
@@ -111,7 +121,7 @@ public Object report(final Argument[] args, final Context ctx)
                     }
                 }
             }
-            
+
             // Add all agents/patches (including first element) to collection
             Collection<Agent> inputCollection = new ArrayList<>();
             inputCollection.add((Agent)first);
@@ -130,14 +140,15 @@ public Object report(final Argument[] args, final Context ctx)
                             new DistanceMetricNetLogoPatchVariable(fieldIndex) : 
                             // ... treat all others as non-patch agents. 
                             new DistanceMetricNetLogoAgentVariable(field.toUpperCase()))); 
+                // will at least return empty list (not be null)
                 tmpList = clusterer.performClustering();
             } catch (DBSCANClusteringException e) {
                 throw new ExtensionException(e);
             }
 
             // Convert generated lists of clusters to nested LogoList
             LogoListBuilder list = new LogoListBuilder();
-            
+
             for (ArrayList<Agent> intList: tmpList) {
                 LogoListBuilder internalBuilder = new LogoListBuilder();
                 for (Agent agent: intList) {
@@ -170,8 +181,8 @@ public Object report(final Argument[] args, final Context ctx)
                 throws ExtensionException, LogoException {
 
             AgentSet inputValues = null;
-            int minNumberOfElements = -1;
-            double maxDistance = -1;
+            int minNumberOfElements = -9999;
+            double maxDistance = -9999;
 
             try {
                 inputValues = args[0].getAgentSet();
@@ -180,29 +191,37 @@ public Object report(final Argument[] args, final Context ctx)
             } catch (Exception e) {
                 throw new ExtensionException(e.getMessage());
             }
-            
+
             if (inputValues == null || inputValues.isEmpty()) {
                 throw new ExtensionException(DBSCANExtensionErrors.ERROR_MISSING_INPUT_DATA);
             }
 
-            if (minNumberOfElements == -1) {
+            if (minNumberOfElements == -9999) {
                 throw new ExtensionException(DBSCANExtensionErrors.ERROR_MISSING_MINIMUM_NUMBER_OF_ELEMENTS);
             }
 
-            if (maxDistance == -1) {
+            if (minNumberOfElements <= 1) {
+                throw new ExtensionException(DBSCANExtensionErrors.ERROR_INVALID_MINIMUM_NUMBER_OF_ELEMENTS);
+            }
+
+            if (maxDistance == -9999) {
                 throw new ExtensionException(DBSCANExtensionErrors.ERROR_MISSING_MAXIMUM_DISTANCE_OF_ELEMENTS);
             }
 
+            if (maxDistance < 0) {
+                throw new ExtensionException(DBSCANExtensionErrors.ERROR_NEGATIVE_MAXIMUM_DISTANCE_OF_ELEMENTS);
+            }
+
             // Convert input AgentSet to Collection
             Iterator<?> it = inputValues.agents().iterator();
-            
+
             // Check for patches
             boolean patches = false;
             Object first = it.hasNext() ? it.next() : null;
             if (first.getClass().equals(Patch.class)) {
                 patches = true;
             }
-            
+
             // Add all agents/patches (including first element) to collection
             Collection<org.nlogo.api.Agent> inputCollection = new ArrayList<>();
             inputCollection.add((org.nlogo.api.Agent)first);
@@ -220,7 +239,8 @@ public Object report(final Argument[] args, final Context ctx)
                             // For patches, use patch-specific coordinate fields 
                             new DistanceMetricNetLogoPatchLocation() :
                             // ... treat all others as non-patch agents.
-                            new DistanceMetricNetLogoAgentLocation())); 
+                            new DistanceMetricNetLogoAgentLocation()));
+                // will at least return empty list (not be null)
                 tmpList = clusterer.performClustering();
             } catch (DBSCANClusteringException e) {
                 throw new ExtensionException(e);

src/main/java/org/nlogo/extensions/dbscan/DBSCANExtensionErrors.java

@@ -3,15 +3,19 @@
 /**
  * Error messages for DBSCAN extension.
  * 
+ * Website: https://github.com/chrfrantz/NetLogo-Extension-DBSCAN
+ * 
  * @author <a href="mailto:[email protected]>Christopher Frantz</a>
- * @version 0.3 (28.05.2019)
+ * @version 0.3 (30.05.2019)
  *
  */
 public final class DBSCANExtensionErrors {
 
 	public static final String ERROR_MISSING_INPUT_DATA = "Clustering input data (e.g., turtles, patches) has not been provided (or is empty).";
 	public static final String ERROR_MISSING_CLUSTER_VARIABLE = "Cluster variable has not been specified.";
+	public static final String ERROR_INVALID_MINIMUM_NUMBER_OF_ELEMENTS = "Minimum number of cluster elements cannot be smaller than 2.";
 	public static final String ERROR_MISSING_MINIMUM_NUMBER_OF_ELEMENTS = "Minimum number of cluster elements has not been specified.";
+	public static final String ERROR_NEGATIVE_MAXIMUM_DISTANCE_OF_ELEMENTS = "Maximum distance of cluster variable values cannot be negative.";
 	public static final String ERROR_MISSING_MAXIMUM_DISTANCE_OF_ELEMENTS = "Maximum distance of cluster variable values has not been specified.";
 	public static final String ERROR_CLUSTER_PATCHES_NOT_SUPPORTED_IN_NETLOGO_5 = "Clustering of patches by variables is not supported for NetLogo 5 version of the DBSCAN extension. " +
 			"Upgrade to NetLogo 6 or higher to use this feature.";

src/main/java/org/nlogo/extensions/dbscan/metrics/DistanceMetricNetLogoAgentLocation.java

@@ -7,9 +7,11 @@
 
 /**
  * Distance metric implementation for agent locations.
+ * 
+ * Website: https://github.com/chrfrantz/NetLogo-Extension-DBSCAN
  *
  * @author <a href="mailto:[email protected]>Christopher Frantz</a>
- * @version 0.3 (28.05.2019)
+ * @version 0.3 (30.05.2019)
  *
  */
 public class DistanceMetricNetLogoAgentLocation implements DistanceMetric<Agent>{

src/main/java/org/nlogo/extensions/dbscan/metrics/DistanceMetricNetLogoAgentVariable.java

@@ -7,9 +7,11 @@
 
 /**
  * Distance metric implementation for agent variables.
+ * 
+ * Website: https://github.com/chrfrantz/NetLogo-Extension-DBSCAN
  *
  * @author <a href="mailto:[email protected]>Christopher Frantz</a>
- * @version 0.3 (28.05.2019)
+ * @version 0.3 (30.05.2019)
  *
  */
 public class DistanceMetricNetLogoAgentVariable implements DistanceMetric<Agent>{

src/main/java/org/nlogo/extensions/dbscan/metrics/DistanceMetricNetLogoPatchLocation.java

@@ -7,9 +7,15 @@
 
 /**
  * Distance metric implementation for patch locations.
+ * 
+ * While clustering patches by location does not really make sense,
+ * perhaps future NetLogo features (e.g., sparse patch matrices) may warrant
+ * the use.
+ * 
+ * Website: https://github.com/chrfrantz/NetLogo-Extension-DBSCAN
  *
  * @author <a href="mailto:[email protected]>Christopher Frantz</a>
- * @version 0.3 (28.05.2019)
+ * @version 0.3 (30.05.2019)
  *
  */
 public class DistanceMetricNetLogoPatchLocation implements DistanceMetric<Agent>{

src/main/java/org/nlogo/extensions/dbscan/metrics/DistanceMetricNetLogoPatchVariable.java

@@ -7,9 +7,11 @@
 
 /**
  * Distance metric implementation for patch variables.
+ * 
+ * Website: https://github.com/chrfrantz/NetLogo-Extension-DBSCAN
  *
  * @author <a href="mailto:[email protected]>Christopher Frantz</a>
- * @version 0.3 (28.05.2019)
+ * @version 0.3 (30.05.2019)
  *
  */
 public class DistanceMetricNetLogoPatchVariable implements DistanceMetric<Agent>{