Skip to content
This repository has been archived by the owner on Feb 19, 2024. It is now read-only.

Mapspec Documentation [WIP]

Jump to bottom
Conor Kelly edited this page Nov 7, 2018 · 35 revisions

Contents

Intro

The layers config tells Gisida how to generate Mabox layers and is an array of key:value where the key is the layer id and the value is the actual config.

var layer = {
    id: 'my-first-layer',
    label: 'My First Layer!',
    ...
}

[Back To Top]

label

string - The text displayed in the layer selector and map legends.

{
    "label": "My Very First Layer"
    ...
}

[Back To Top]

type

string (line|fill|circle|symbol) - The type of mabox to be generated. (todo - link mapbox layer specs)

property

string- The column name of the data to be rendered by the layer

[Back To Top]

properties

array (of strings)

[Back To Top]

is-radius-distance

boolean - For circle layers only, setting to true will handle circle radii as distances rather than data visualization encoding. (Defaults to false)

radius-unit

string (m|km) - For distance circles only, the length unit of the distance data so that gisida can convert to meters. (To do: add conversions for mi|ft)

[Back To Top]

source

object - The configuration specifying what data to use in the layer.

source.type

string (geojson|vector) - Specifies what type of Mapbox layer to generate. Vector layers utilize Mapbox tilesets and are good for large datasets (requires source.layer and source.url). Geojson layers load static datasets from local CSV or GEOjson files and requries source.data.

Note - Unlike geojson layers, vector layer sources cannot be fetched or updated locally and must be maintained via Mapbox Studio

source.data

string|array|number - Identifies which data sources to use for the layer and are loaded and processed when the layer is enabled for the first time. String values reference local files while number values will fetch data from the ONA.io forms with matching IDs. Arrays can be used to list multiple data sources which will be merged when all data is fetched.

"my-geojson-layer": {
	...
	"source": {
		"type": "geojson",
		"data": "data/some-data.geojson"
	}
},
"my-merged-geojson-layer": {
	...
	"source": {
		"type": "geojson",
		"data": [
			"data/some-data.geojson",
			123456,
			"data/some-other-data.csv"
		]
	}
},
"my-vector-layer": {
	...
	"source": {
		"type": "vector",
		...
		"data": "data/some-supplemental-data.csv"
	}
}

Note - Data loaded for vector layers are stored in system memory, not the Mapbox layer source, meaning this data cannot be used in Mapbox expressions for features such as filters or styling. However, data loaded for geojson layers is provided as the layer source when generating the Mabox layer and is thus available to all Mapbox expression features.

source.join

array -

"join": [
       		"site_id",
       		"site_id",
       		"facility_site_id",
       		"facility_site_id",
       		"Fixed Site Unique ID"
       ]

source.layer

string (for vector layers only) - The layer ID of the tileset hosted on Mapbox.

source.url

string (for vector layers only) - The layer URL of the tileset hosted on Mapbox.

[Back To Top]

categories

"categories": {
     "breaks": "no",
     "color": ["#FFDC00", "#FF851B", "#FF4136"],
     "limit": [0.1, 0.149, 1],
     "label": ["Low", "Moderate", "Severe"]
   }

categories.breaks

string (yes|no) -

"breaks": "no"

categories.color

string|array (of strings) - colors in Hex format, aligning with each different category

"color": ["#FFDC00", "#FF851B", "#FF4136"]

categories.limit

array (of integers) -

"limit": [0.1, 0.149, 1]

categories.label

array (of strings) - labels for the different categories

"label": ["Low", "Moderate", "Severe"]

[Back To Top]

aggregate

"aggregate": {
     "type": "sum",
     "filter-values": ["1"],
     "min": 10,
     "filter": "Partner",
     "sub-filter": "Sub_Partner",
     "accepted-filter-values": ["BRCiS", "SCOPE", "UNFAO"],
     "accepted-sub-filter-values": ["UNICEF"],
     "group-by": "district_id",
     "timeseries": {
       "type": "cumulative",
       "field": "period"
     }
   }

aggregate.type

string -

"type": "sum"

aggregate.filter

string -

"filter": "Partner"

aggregate.sub-filter

string -

"sub-filter": "Sub_Partner"

aggregate.accepted-filter-values

array (of strings) -

"accepted-filter-values": ["BRCiS", "SCOPE", "UNFAO"]

aggregate.accepted-sub-filter-values

array (of strings) -

"accepted-sub-filter-values": ["UNICEF"]

aggregate.filter-label

array (of strings) -

"filter-label": ['', 'Type of Site', 'Location']

aggregate.timeseries

object (of strings) -

"timeseries": {
       "type": "cumulative",
       "field": "period"
     }

aggregate.timeseries.type

string -

"type": "cumulative"

aggregate.timeseries.field

string -

"field": "period"

aggregate.timeseries.submission-date-field

[Back To Top]

parse-data

A configuration object mapping out how to handle certain layer data using data values as keys to reference simple replacements or parsing options for ONA.io select-multiple questions. The original data is stored on the returned parsed datum object as unparsedDatum.

/* Raw Data */
var data = [{
  'Type of site': 'Hospital',
  'Services': 'OTP'
}, {
  'Type of site': 'hospital',
  'Services': 'MCH TSP'
}, {
  'Type of site': 'Health post',
  'Services': 'MCH Other',
  'Other Services': 'Nutrition Counseling'
}];

/* Data Parse Config */
var dataParse = {
  'Type of site': {
    'key': {
      'hospital': 'Hospital',
      'Health post': 'Health Post'
    }
  }
  'Services': {
    'key': {
      'MCH': 'Maternal and Child Health',
      'OTP': 'Outpatient Therapeutic Program',
    },
    'type': 'multiple',
    'split': ' ',
    'join': ', ',
    'other-prop': 'Other Services',
    'other-value': 'Other'
  }
}

/* Parsed Data */
[{
  'Type of site': 'Hospital',
  'Services': 'Outpatient Therapeutic Program'
}, {
  'Type of site': 'Hospital',
  'Services': 'Maternal and Child Health, TSP'
}, {
  'Type of site': 'Health post',
  'Services': 'Maternal and Child Health, Nutrition Counseling'
}]

parse-data.key

object (of strings) - keys to convert the input data into the properly formatted parsed data. For example, when the service OTP is passed in, the parsed data will return Outpatient Therapeutic Program due to the key.

parse-data.type

string (single|multiple) -

parse-data.other-prop

string -

parse-data.other-value

string -

[Back To Top]

detail-view

The DetailView is a sidebar component which can be populated by basic information from the joined layer data and the feature which has been clicked (joining via unique identifier detail-view.UID). To parse raw data into human readable formats, use the parsing schema for title, sub-title, and basic-info[value|alt] properties.

/* Detail View Schema */
var detail-view = {
  UID: "",
  title: (string|spec),
  sub-title: (string|spec),
  basic-info: [{
    value: (string|spec),
    icon: (string|iconOption),
    alt: (string|spec),
  }]
};


/* Parsing Schema Spec */
var spec = {

  prop: (string|array),
  // Required, array contains strings or nested spec objects.
  // string - The single property to check for a given value without parsing.
  // array  - A list of specs which will be iterated over.
              If spec.join is undefined, the first truthy property value will be used,
              otherwise a the whole list will be returned as a string.


  mustache: (string),
  // Optional, Mustache renders this string with spec.prop (may include HTML)

  join: (string),
  // Optional, The string by which to join an array of spec.prop(s) for stringifying

}

detail-view.UID

(Required) string The property on the MapBox feature (feature.properties) which acts as a unique identifier.

"UID": "site_id"

detail-view.title

(Required) string|spec This populates the title element of the detail view component using the parsing spec.

"title": {
  "prop": "facility_combined_label",
  "mustache": "{{{facility_combined_label}}}"
}

detail-view.sub-title

string|spec This populates the sub-title element of the detail view component using the parsing spec.

"sub-title": {
  "prop": "NU_indicators/facility_type",
  "mustache": "{{{NU_indicators/facility_type}}}"
}

detail-view.basic-info

[spec] The list of items to populate basic information from joined / feature data.

"basic-info": [{
  "value": {
    "prop": ["Longitude", "Latitude"],
    "join": ", "
  },
  "icon": "map-marker",
  "alt": "GPS coordinates"
},{
  "value": {
    "prop": ["settlement_label", "NU_indicators/district_label", "NU_indicators/region_label"],
    "join": ", "
  },
  "icon": "globe", 
  "alt": "Site Location"
},{
  "value": {
    "prop": "partner_details/organisation",
    "mustache": "{{{partner_details/organisation}}}"
  },
  "icon": "user",
  "alt": "Organization"
},{
  "value": "NU_indicators/donor",
  "icon": "user",
  "alt": "Donor(s)"
}]

detail-view.basic-info.value

string|spec (Required) The text or HTML to be rendered in each <li> of the basic-info list using the parsing spec.

/* Examples */
var datum = {
  'Site name': 'Bandiradley',
  'Type of site': 'Health Post',
};
var detailView = {
  ...
  'basic-info': [{
    'value': 'Site name',
    ...
  }, {
    'value': { 
      'prop': 'Site name',
      'mustache': 'Name: {{Site name}}'
    },
    ...
  }, {
    'value': { 
      'prop': ['name', 'Site name'],
  }, {
    'value': { 
      'prop': ['Site name', Type of site'],
      'join': ' - '
    },
    ...
  }]
};

/* Renders As: */
  • Bandiradley
  • Name: Bandiradley
  • Bandiradley
  • Bandiradley - Health Post

detail-view.basic-info.icon

string|spec Determines which glyphicon symbol to use as a list item bullet.

string - This should be a symbol from glyphicon formatted so it does not include "glyphicon-"

object - An options object allows for conditional formatting using the value of icon.prop.

/* Icon Options */
var iconOptions = {
  prop: (string),
  // Required, property/value to conditionally determine icon options

  [feature.properties[icon.prop]]: {
  // Required per condition

    glyph: (string), // Required, the glyphicon string to use
    color: (string), // An HTML color string to use to color the icon
    alt: (string|spec) // A string or parse spec for alt under this condition,
                       // if defined this will overwrite the detail item alt
  }
}

/* Examples */
var datum = {
  'Site name': 'Bandiradley',
  'Type of site': 'Health Post',
};
var detailView = {
  ...
  'basic-info': [{
    ...
    'icon': 'arrow-right'
  }, {
    ...
    'icon': {
      'prop': 'Type of site',
      'default' 'minus', // not yet implemented
      'Health Post': {
        glyph: 'home',
        alt: 'Health Post',
      },
      'Hospital': {
        glyph: 'plus',
        color: '#FF0000',
        alt: {
          prop: 'Site name',
          mustache: 'Hospital: {{Site name}}'
        },
      },
      'Chemist': 'plus-sign',
    }
  }]
};

feature-detail.basic-info.alt

string|spec Used for Alt and Title html properties for tooltip content.

string - A simple text value

object - A parsing spec object to dynamically generate text

[Back To Top]

labels

"labels": {
     "data": "data/som_region_labels.csv",
     "label": "<b> {{percent_displaced}}% </b> <br> of {{population}}",
     "join": ["osm_id", "region_id"],
     "coordinates": ["longitude", "latitude"],
     "minzoom": 4.5,
     "height": 30,
     "width": 30,
     "offset": [-15, -5]
   }

labels.data

string (.csv file) - path to data file

"data": "data/som_region_labels.csv

labels.label

string - information for the label based on data

"label": "<b> {{percent_displaced}}% </b> <br> of {{population}}"

labels.join

array (of strings) -

"join": ["osm_id", "region_id"]

labels.coordinates

array (of strings) -

"coordinates": ["longitude", "latitude"]

labels.minZoom

integer - limit for how far out you can zoom

"minzoom": 4.5

labels.height

integer - vertical size

"height": 30

labels.width

integer - horizontal size

"width": 30

labels.offset

array (of integers) - the distance a label is placed from its feature. Measured from the edge of the label to the edge of the feature symbol

"offset": [-15, -5]

[Back To Top]

merge-locations

boolean - Whether or not locations are merged

"merge-locations": true

no-outline

boolean - whether or not there is an outline

"no-outline": true

charts

boolean - whether or not charts are part of this layer

visible

boolean - changes if the layer is selected or not. If selected, value changes to true, but is false by default

"visible": false

credit

string - Information about the layer

"credit": "Internal Displacements (1 Jan to 31 December 2017)<br> Updated: March 16th, 2018"
Clone this wiki locally