Skip to content

Developer's Reference

sztanko edited this page Jan 3, 2013 · 13 revisions

#Configuration reference

Although there is a very minimal configuration needed for Crosslet to start working, there are lots of thing you can customize, things like number formats, legend texts and color scales.

Here is the full reference of it:

config=
	map: mapConfig
	data: dataConfig
	dimensions: dimensionMapConfig
	defaults: defaultConfig

mapConfig

	leaflet: leafletConfig
	view: viewConfig
	geo: geoConfig

leafletConfig

These map supplies some essential configuration values which will be passed to leaflet.

  • key: String. mandatory field Your cloudmade api key. Obtain yours at Cloudmade developers aread
  • styleId: Integer. Your map style. Default is the minimalistic map # 64657. You can choose any from here
  • attribution: String. The text which will appear at the bottom right corner of the map. Default value is "Map data © OpenStreetMap contributors, CC-BY-SA, Imagery © CloudMade". Please do not forget to credit OpenStreetMap contributors.

viewConfig

These values will be passed to Leaflet as well, but refer to the initial positioning of the map

  • center: Array of two doubles. Initial coordinates of the center of the map. Default is [51.505, -0.09], which is the center of London. You probably want to change it.
  • zoom: Zoomlevel. Integer, 1 to 18. Default is 11, which is perfect for London.

geoConfig

  • url: mandatory. String. Location of you file containing geoJSON geometry of your statistical units. Polygon or Multipolygon features are accepted. We expect you know how to deal with GeoJSON data. You can get many of the units from GeoNames. You can also use TopoJSON extension. Here is some tutorial on map creation, which also covers generation of GeoJSON files and topojson.
  • name_field: String. the name of the field in properties of each feature that is a name of the area. This will be displayed when you hover over a mouse (unless you override this behaviour). Default value is " name ".
  • id_field: String. the name of the field in the properties of each feature which is the code of the area. This will be the join key of the data. E.g., if you are displaying some data from US Census Bureau, this will be probably fips code, and so on.
  • topo_object: String. This is mandatory only in case you are using TopoJSON extension of geoJSON. Since it can hold multiple geometry sets, you have to select which one to use. In most cases it will be the name of the original geoJSON file which was simplified using TopoJSON.

DataConfig

This part of configuration describes the ways how to handle the datasets. As dataset, Crosslet expects either a tsv or csv or a json file containing an array of simple objects (associative arrays).

  • version: String. Currently it is not used, but will be handy in the next versions of Crosslet, where the datasets will be cached on the client's side. By changing this value you force reload of the cached datasets.
  • id_field: The name of the field which contains the code of each administrative area. E.g, for US Census Bureau, this probably will be the fips code of the area. Knowing the code and provided the same code is used in GeoJSON id field, Crosslet will know which polygon to associate with it.

dimensionsMapConfig

This is a map of objects, each of which represents a statistical measure. E.g. if we would like to show 2 measures, e.g. percentage of votes for democratic party candidate and percentage of votes for GOP, there will be two objects. Each of this objects will have a separate box on the top panel.

Each element of this map looks like this:

render: renderConfig
format: formatConfig
p: params
data: dataConfig
submitter: submitterFunction

renderConfig

You can override the default view of each box using the render functions in the renderConfig. Here is an explanation which function renders which part.

Anatomy of a dimension box:

<div class="box">
	<div class="legend">
		<div class="legendText"> <!-- This part is shown when the box is not active and not hovered -->
			<div class="legendText_p">...This part is rendered by renderConfig.legend function</div>
			<div class="legendText_p">...This part is rendered by renderConfig.range function</div>
		</div>
		<div class="legendForm"> <!-- This part is shown when the box is active or hovered -->
			<div class="legendForm_p">...This part is rendered by renderConfig.form function</div>
			<div class="legendForm_range">...This part is rendered by renderConfig.rangeForm function</div>
		</div>
	</div>
	<div class="graph">
		Here is the bar chart. It is rendered by Crosslet and cannot be overriden.
	</div>
</div>

Check init.cofee for the definitions of default rendering functions. Each box can be in active (selected) or passive states. When active or hovered, it is shown as form. You can also specify a form in the Legend part of the box as well. When any of it's inputs are changed, config.submitter function is executed, which you can override. Values of the form inputs are then are stored in params.

.m0 and .m1 classes

In case the range is modified (filter is applied), content of elements with class .m0 and .m1 are populated with new lower and upper values of the range. In case of legend, this can be any elements, in case of form, these should be input type="text" values.

format

formatConfig is a map of four functions. Each of this functions return a format function (a function which returns a formatted string of it's argument) and take the dimensionConfig as an argument. See init.coffee for default values of the functions.

  • short: default formatting of a value, will be shown while rendering the range on legend.
  • long: extended format of a value, this one is used to show text when a shape is hovered on map.
  • input: format of the range form values. Must output numeric values.
  • axis: format of the bar chart axis values. Since there is not enough place near an axis tick, this should be an ultra short value.

Here is a short example. Let's say we want to display average rental price of houses for each region. For a value of 350 we will probably define the following formatters:

  • short() should output "£350 p/w"
  • long() should output "£350 per week (£1,516 per month)"
  • input() should return "350"
  • axis() should give us "£350"

params

By default, each box represents one statistical value. But in more complex cases, a box also can be a form and it will can show different variables. Params represents the default values of the field.

dataConfig

  • dataSet: this can be either a url of dataset, a function that returns a url of dataset or an array object which already contains the dataset. Please note that each url is loaded only once, regardles of how many dimensions specify it as their dataSet.
  • method: d3.tsv # Method which will be used to retrieve the url. Use d3.tsv for tab separated files, d3.csv for comma separated files and d3.json for json representation of data. Default is d3.tsv
  • field: String or function. Field in the dataset which will be used for identifying the data. In complex boxes you can specify a function which will return the field name based on the parameters of the legend form.
  • preformat: Function that returns integer. Once data is loaded, we might want to transform the data in some way. For example, if there are absolute values and we would like to show percentages, we can write a converting function which will be called for each value of the dataset. By default, the preformatting function is identity, that is returns the original value.
  • ticks: Integer or an array of numeric values. In case of integer, this specifies number of ticks on the bar chart. See d3.axis.ticks(). In case of array of numeric value, axis ticks are explicitly specified.
  • colorscale: Color scale to be used. This must be a d3 scale which maps a domain of [1,20] to some colors. Default is d3.scale.linear().domain([1,10,20]).range(["green","yellow", "red"]).interpolate(d3.cie.interpolateLab)
  • exponent: This is an experimental features. It is very often that dataset values follow exponential or lognormal distribution, thus making the bars on the chart look extremely skewed and useless. Exponent is to ballance the axis. To be very simple If the distribution is skewed to the left, use values between 0 and 1 . If the distribution is skewed to the right, use values larger then 1.

submitterFunction

Every time any input or select of the legend form is changed,

  • submitterFunction(dimension_config, element) function is called to populate the p object of the dimension config. This function is given an html element within which all the inputs are located. It should find out their values and return and associative array of an arbitrary depth, which will be then assigned to dimension_config.p variable.
  • All the boxes are redrawn. Render functions are called and bar charts are re-rendered.
Clone this wiki locally
You can’t perform that action at this time.