DensityQuery Class
Controls the resolution and the amount of Gaussian blur for rasters from a DensityDataSet.
NuGet/Assembly: Carmenta.Engine.5.16.2.nupkg (in the CEDataSets assembly)
Syntax
public class DensityQuery : QueryRemarks
The DensityDataSet generates rasters of estimated density from an embedded point dataset. The straightforward approach to estimate density would be to use no smoothing, but simply count the number of points in each raster cell (or their total weight), and then divide by the cell area in square kilometers. Such a raster would represent a 2D histogram. However, histograms are not considered to be the best way to estimate density.
Instead, a statistical smoothing method known as kernel density estimation is used, where a kernel function determines how the contribution from each point shall be smoothed out over several nearby raster cells.
Statisticians have designed several classes of kernel functions that could be used, but there is agreement that the choice of kernel class is not crucial. What's important is the choice of the kernel bandwidth: a distance parameter that controls the amount of smoothing. Carmenta Engine uses the normal or Gaussian kernel, which is a bivariate normal distribution function. The standard deviation is the same in the x and the y directions, so the kernel has rotational symmetry. For this class of kernel functions, the bandwidth is defined to be the standard deviation. In a DensityQuery, you can specify the standard deviation as the Blur, and you can specify whether the value is expressed in meters or screen pixels by using the BlurLengthUnit.
Two examples of Gaussian kernel functions are illustrated below; for more details about how the smoothing is done, see Blur.
 |
 |
It is not trivial to choose the blur value. If it is chosen too large, the smoothing will obscure details that may be interesting. If it is chosen too small, the map may be cluttered with details that are not statistically significant. However, we think that most Carmenta Engine users will not really use the DensityDataSet for statistical analysis (estimating a probability density function from a point sample), but for cartography (making a readable map). So we suggest that you simply try different blur values until the map looks good, subjectively.
The reason why the smoothing parameters have been placed in the DensityQuery class is that no smoothing is used when the DensityDataSet constructs its spatial index. Instead, all smoothing occurs at runtime during an update, so it is more flexible to have the smoothing controlled by the density query. Note that you can have several instances of ReadOperator which refer to the same DensityDataSet but uses different density queries.
Here are some screenshot examples of a large point dataset and different amount of density smoothing.
First the original point data:
 |
This visualization is inefficient since there are about 117 000 points in the dataset, and it doesn't show the points very well. The low alpha value of the color helps a little, but the Göteborg area is still a nearly uniform black, and if we lower the alpha even more it would be hard to see the more isolated points. One can also argue that the map tries to show too much detail for this scale: cartographic symbols are normally larger. (A screenshot using larger circles can be found under DensityDataSet.)
So let us use a DensityDataSet instead, with different values of blur. The same color table for the density raster has been used in all screenshots.
 |
 |
 |
 |
Inheritance Hierarchy
System.Object (not available in C#)
EngineObject
ResourceObject
Query
DensityQuery
Platforms
Windows, Linux, Android
DensityQuery Members
The DensityQuery type has the following members.
Constructors
| Name | Description |
|---|---|
| DensityQuery | Initializes a new instance of the DensityQuery class. |
Properties
| Name | Description |
|---|---|
| Blur | Gets or sets the bandwidth (standard deviation) of the smoothing kernel. |
| BlurLengthUnit | Gets or sets the length unit for the Blur value. |
| CroppingFactor | Gets or sets a factor that, when multiplied with the Blur, determines the cropping radius. |
| IsDisposed | Gets a value that tells whether the current DensityQuery has been disposed. Inherited from EngineObject |
| Name | Gets or sets the name of the DensityQuery. Inherited from ResourceObject |
| NativeHandle | Gets the native Carmenta Engine kernel object the current DensityQuery represents. Inherited from EngineObject |
| ReadLines | Gets or sets a flag indicating if line features should be read from the dataset. Inherited from Query |
| ReadMeshes | Gets or sets a flag indicating if mesh features should be read from the dataset. Inherited from Query |
| ReadMultiGeometries | Gets or sets a flag indicating if multi-geometry features should be read from the dataset. Inherited from Query |
| ReadMultiLines | Gets or sets a flag indicating if multi-line features should be read from the dataset. Inherited from Query |
| ReadMultiPoints | Gets or sets a flag indicating if multi-point features should be read from the dataset. Inherited from Query |
| ReadMultiPolygons | Gets or sets a flag indicating if multi-polygon features should be read from the dataset. Inherited from Query |
| ReadPoints | Gets or sets a flag indicating if point features should be read from the dataset. Inherited from Query |
| ReadPolygons | Gets or sets a flag indicating if polygon features should be read from the dataset. Inherited from Query |
| ReadRasters | Gets or sets a flag indicating if raster features should be read from the dataset. Inherited from Query |
| ResolutionFactor | Gets or sets a value that adjusts the resolution a ReadOperator requests when it reads data from a DataSet. Inherited from Query |
| IUserProperties.UserProperties | Gets the AttributeSet that contains the user properties. Inherited from IUserProperties |
Methods
| Name | Description |
|---|---|
| Clone | Creates a copy of an object. Inherited from EngineObject |
| Dispose | Releases the reference to the native Carmenta Engine kernel instance the EngineObject represents. Inherited from EngineObject |
| Equals | Determines whether this instance is equal to another. Inherited from EngineObject |
| Match | Checks if a Feature matches the Query. Inherited from Query |