31:T475,mainMap = html`

circle-color: rgba(255, 255, 255, 0.3); circle-stroke-color: $circleStrokeColor; circle-stroke-width: $circleStrokeWidth; circle-radius: @no2 ? @no2 / 5 : 5;

text-field: @name; text-size: interpolate(linear(), zoom(), 12, 10, 18, 20); text-color: white; text-variable-anchor: ['top']; text-radial-offset: 1.8;

`32:[] 2f:{"title":"Flo.w Helper Library Examples","cells":[{"id":0,"value":"# Flo.w Helper Library Examples","pinned":false,"hidden":false,"mode":"md"},{"id":33,"value":"Flow.toc(\"h2,h3\")","pinned":false,"hidden":false,"mode":"ojs"},{"id":12,"value":"## Introduction","pinned":false,"hidden":false,"mode":"md"},{"id":38,"value":"This notebook shows how to use the Flo.w Helper Library for Observable. First let's define the Flo.w configuration we want to use in this notebook. At a minimum you need to define an `apiKey`. Other options are discussed in the [Flo.w Helper Library API](https://observablehq.com/@emuanalytics/flow-helper-library-v2) but all have sensible defaults:","pinned":false,"hidden":false,"mode":"md"},{"id":7,"value":"config = ({\n apiKey: \"b6b77cc4-904a-46d1-aa0f-3bf3848ce4c7\",\n // Optional\n version: \"latest\",\n initialState: {\n prop1: \"a test property\",\n prop2: 42,\n circleStrokeColor: \"#eeee00\",\n circleStrokeWidth: 2\n }\n})","pinned":true,"hidden":false,"mode":"ojs"},{"id":42,"value":"Next, we import the Flo.w Helper Library. We inject our configuration using the `import with` syntax.","pinned":false,"hidden":false,"mode":"md"},{"id":9,"value":"import { Flow } with { config as config } from \"@emuanalytics/flow-helper-library-v2\"","pinned":true,"hidden":false,"mode":"ojs"},{"id":46,"value":"The library is now ready to use. All library functions are available as properties of the `Flow` object.","pinned":false,"hidden":false,"mode":"md"},{"id":13,"value":"## Documenting Datasets \n\nObservable notebooks form an important part of the documentation process during data discovery *and* project delivery. The Flo.w helper library provides several functions to simplify the process of documenting datasets. The functions can be used *individually* or *combined* into a complete dataset summary.","pinned":false,"hidden":false,"mode":"md"},{"id":313,"value":"1. **Combined: datasetSummary**\n","pinned":false,"hidden":false,"mode":"md"},{"id":242,"value":"Flow.datasetSummary(\"airquality_with_params\", { headingLevel: 3 })","pinned":true,"hidden":false,"mode":"ojs"},{"id":247,"value":"2**. Individual:**\nTo include individual aspects of dataset documentation you can use the following functions:\n\n- `datasetTable()` - display a table of all available datasets.\n- `datasetAttributes(datasetId)` - display a table of a dataset's attributes.\n- `datasetSource(datasetId)` - display a datasets's `source` formatted as SQL.\n\nSee [Flo.w Helper Library API](https://observablehq.com/@emuanalytics/flow-helper-library-v2) for full details about these functions.","pinned":false,"hidden":false,"mode":"md"},{"id":17,"value":"## Querying Datasets","pinned":false,"hidden":false,"mode":"md"},{"id":173,"value":"The Flo.w helper library provides functions to assist with making Flo.w dataset queries and viewing results.\n\nSee [Flo.w Query Definitions](https://developer.emu-analytics.net/docs/flow-engine/datasets/dataset-queries.html#flo-w-query-definitions) for information on how to define a query.\n\n\n","pinned":false,"hidden":false,"mode":"md"},{"id":182,"value":"### Running a query\n\nUse the `datasetQuery` function to query a dataset:","pinned":false,"hidden":false,"mode":"md"},{"id":186,"value":"queryResults = Flow.datasetQuery({\n datasetId: \"airquality_with_params\",\n where: {\n name: { $like: \"B%\" }\n },\n params: {\n no2_filter: 50\n },\n format: \"json\"\n})\n","pinned":true,"hidden":false,"mode":"ojs"},{"id":194,"value":"### Displaying query results as a table - viewof\n\nThe `datasetQueryTable` function allows you to perform a query and display the results as a table. Using Observable's `viewof` syntax, the underlying query results are still available for using in other cells.\n\nThe table uses virtual-scrolling so can easily handle results with 1000s of rows.\n
\nIt also supports row selection: if rows are selected then the value of the cell is the subset of selected data rather than the full results array.\n\nSee [Observable Inputs library](https://observablehq.com/@observablehq/input-table) for table options that can be passed as a second parameter to the `datasetQueryTable` function.\n","pinned":false,"hidden":false,"mode":"md"},{"id":202,"value":"viewof queryResults2 = Flow.datasetQueryTable(\n {\n datasetId: \"airquality_with_params\",\n limit: 100,\n order: [[\"no2\", direction]]\n },\n { layout: \"auto\" }\n)","pinned":true,"hidden":false,"mode":"ojs"},{"id":328,"value":"direction = \"asc\"","pinned":true,"hidden":false,"mode":"ojs"},{"id":209,"value":"queryResults2\n","pinned":true,"hidden":false,"mode":"ojs"},{"id":215,"value":"### A note about Flo.w RDF reactive queries\n\nFlo.w RDF supports registering reactive queries that re-run when referenced reactive state properties change. This is very useful when developing an application. However, in Observable notebooks we have found that mixing Observable's cell-based reactivity with Flo.w RDFs state-based reactivity can lead to confusion and difficult-to-debug notebooks. \n\nIt is usually better to rely on Observable's cell-based reactivity and use an explicit query as shown above.* Your query will re-run if you reference Observable cell values in the query definition just like a reactive Flo.w query does in an application*. \n
\nThe benefits of using cell-based reactivity include:\n\n- Query results are displayed directly in the notebook\n- Query errors are reported above the notebook cell containing the query\n","pinned":false,"hidden":false,"mode":"md"},{"id":21,"value":"## Working with Maps\n\nThe Flo.w helper library provides function for working with maps to:\n\n- Update map style from Observable cell values\n- Get selected feature IDs\n- Get selected feature properties\n- Handle low level clicks on map features\n\nThe examples below all use this map of air quality data:","pinned":false,"hidden":false,"mode":"md"},{"id":91,"value":"$31","pinned":true,"hidden":false,"mode":"ojs"},{"id":276,"value":"Property| Value\n--------|--------------------------\nID | ${clickedFeature?.id}\nNO2 | ${clickedFeature?.properties.no2}\nlayerID | ${clickedFeature?.layer.id}\nsource | ${clickedFeature?.source}","pinned":false,"hidden":false,"mode":"md"},{"id":150,"value":"### Modifying a map's style based on Observable cell values\n\nFlo.w RDF allows you to style map layers by referencing reactive state properties using the `$propName` syntax. When working with Observable notebooks you probably have a need to update map style based on notebook cell values. The easiest way to do this is to set up a single cell in your notebook that transfers the required notebook cell values to Flo.w RDF reactive state using the `stateMerge` function.\n\nIn the example below Observable inputs are used to control the styling of the map:","pinned":false,"hidden":false,"mode":"md"},{"id":157,"value":"// Slider from the Observable.Inputs library to control circle stroke width\nviewof circleStrokeWidth = Inputs.range([0, 5], {\n label: \"Circle stroke width:\",\n step: 0.1\n})","pinned":false,"hidden":false,"mode":"ojs"},{"id":160,"value":"// Color-picker from the Observable.Inputs library to control circle stroke color\nviewof circleStrokeColor = Inputs.color({\n label: \"Circle stroke color:\",\n value: \"#EEEE00\"\n})","pinned":false,"hidden":false,"mode":"ojs"},{"id":162,"value":"// Observable cell values are transferred to Flo.w RDF reactive state using the stateMerge function.\n// This cell will re-evaluate when either of the the two cell values change. This keeps RDF reactive state in\n// sync with the Observable cell values.\nFlow.stateMerge({\n circleStrokeWidth,\n circleStrokeColor\n})","pinned":true,"hidden":false,"mode":"ojs"},{"id":103,"value":"### Getting selected feature IDs - `mapSelectedFeatureId`\n\nUse the `mapSelectedFeatureId` function to reactively retrieve the selected feature ID(s) for the specified data source. For `single` selection mode the returned value is a single ID. For `multi` selection mode an array of IDs is returned.\n\nThe function takes 2 parameters:\n\n1. The `` element to access:\n - Using a named cell value when defining the map is the easiest way to get hold of this. See map cell above.\n3. The ID of the map data source to access.\n\nClick different features to see the cell value update. Other cells that depend on this value will also update reactively.\n","pinned":false,"hidden":false,"mode":"md"},{"id":122,"value":"selectedFeatureId = Flow.mapSelectedFeatureId(mainMap, \"airqualitySource\") ","pinned":true,"hidden":false,"mode":"ojs"},{"id":132,"value":"Selected feature ID: **${selectedFeatureId}** ","pinned":true,"hidden":false,"mode":"md"},{"id":118,"value":"### Getting selected feature properties - `mapSelectedFeature`\n \nUse the `mapSelectedFeature` function to reactively retrieve the selected feature properties for the specified data source. For `single` selection mode the returned value is a single object of properties. For `multi` selection mode a map from feature IDs to feature properties is returned.\n\nClick different features to see the cell value update. Other cells that depend on this value will also update reactively.\n","pinned":false,"hidden":false,"mode":"md"},{"id":96,"value":"selectedFeatureProps = Flow.mapSelectedFeature(mainMap, \"airqualitySource\") ","pinned":true,"hidden":false,"mode":"ojs"},{"id":129,"value":"Selected feature name: **${selectedFeatureProps?.name}**","pinned":true,"hidden":false,"mode":"md"},{"id":135,"value":"\n### Getting low-level feature click information - `mapClickedFeature`\n\nUse the `mapClickedFeature` function to reactively retrieve low-level information about clicked map features. The returned object contains feature properties, and information about the map layer and data source.\n\nClick different features to see the cell value update. Other cells that depend on this value will also update reactively.\n","pinned":false,"hidden":false,"mode":"md"},{"id":141,"value":"clickedFeature = Flow.mapClickedFeature(mainMap)","pinned":true,"hidden":false,"mode":"ojs"},{"id":144,"value":"Property| Value\n--------|--------------------------\nID | ${clickedFeature?.id}\nlayerID | ${clickedFeature?.layer.id}\nsource | ${clickedFeature?.source}","pinned":true,"hidden":false,"mode":"md"},{"id":290,"value":"### Getting the time from a Flo.w Timer component on a map\n\nFor time-based maps it is convenient to place a Flo.w Timer component in the top-left control container. This provides space to view the timer's calendar control when open.\n\nSet the Timer component's `timer-state` attribute to define the reactive app state property to bind to the timer (typically `$time`). Then, to retrieve the selected time for use in the notebook, use the `stateGet` function. This function returns a generator that will update the cell's value when the reactive state property bound to the Timer changes.\n\nYou can use the resulting cell value in query definitions to re-run queries reactively when the timer changes.","pinned":false,"hidden":false,"mode":"md"},{"id":291,"value":"time = Flow.stateGet(\"time\")","pinned":true,"hidden":false,"mode":"ojs"},{"id":24,"value":"## Working with Flo.w RDF Reactive State","pinned":false,"hidden":false,"mode":"md"},{"id":70,"value":"You very rarely have to work with Flo.w RDF reactive state directly in Observable notebooks when using the helper functions discussed above. In case you do need to access RDF state (for example, if you are experimenting with Flo.w RDF UI components and or reactive queries) there are 3 helper methods that wrap calls to `context.state`:\n\n- `stateGet` - Get a state property reactively. This function returns a generator.\n- `stateSet` - Set a single state property.\n- `stateMerge` - Set multiple properties atomically.\n\nIn the config used to initialise the Flo.w helper library at the top of this notebook, some initial properties was provided to populate the RDF reactive state.\n\nWe can get one of those properties using `stateGet`:","pinned":false,"hidden":false,"mode":"md"},{"id":55,"value":"aProp = Flow.stateGet(\"prop1\")","pinned":true,"hidden":false,"mode":"ojs"},{"id":80,"value":"From the above cell, it might look like `stateGet` simply retrieves the state property's value when it is called. However, `stateGet` actually returns a generator that will update the cell's value reactively if the state property changes.\n\nIn the example below a range slider is used to select a number. The RDF state property `numberProp` is set to the value of the slider using `stateSet`. In the final cell of the example, `stateGet` is used to retrieve `numberProp`.\n\nAs you move the slider, you will see the 'cell evaluation' indicators flashing to the left of the cells showing that they are being re-evaluated as things change.","pinned":false,"hidden":false,"mode":"md"},{"id":323,"value":"#### Observable Inputs UI","pinned":false,"hidden":false,"mode":"md"},{"id":59,"value":"viewof val = Inputs.range([0, 100], { label: \"Amount:\", step: 1 })","pinned":true,"hidden":false,"mode":"ojs"},{"id":302,"value":"#### Setting state:","pinned":false,"hidden":false,"mode":"md"},{"id":64,"value":"Flow.stateSet(\"numberProp\", val); ","pinned":true,"hidden":false,"mode":"ojs"},{"id":300,"value":"#### Getting state:","pinned":false,"hidden":false,"mode":"md"},{"id":65,"value":"valFromState = Flow.stateGet(\"numberProp\")","pinned":true,"hidden":false,"mode":"ojs"},{"id":221,"value":"## Working with Vega and Vega-Lite charts - Flow.vega\n\nTo prototype a Vega or Vega-lite chart use the Vega Embed library. For convenience, the embed function is made available as `Flow.vega`. \n\nFlo.w RDF supports registering chart specifications and displaying reactive charts. However, as discussed above under 'Querying Datasets' we have found that it is generally easier to rely on Observable's cell-based reactivity when prototyping charts in a notebook.\n\nTo use the results of a Flo.w query as data for the chart, specify the chart `data` property as shown below. The chart will update if the query results change for any reason.\n\nTo size the chart to fill the cell width, use Observable's reactive `width` variable.\n\n","pinned":false,"hidden":false,"mode":"md"},{"id":224,"value":"Flow.vega({\n data: { values: queryResults2 },\n width: width - 150,\n height: 400,\n mark: { type: \"bar\", tooltip: { content: \"data\" } },\n encoding: {\n x: { field: \"label\", type: \"ordinal\", sort: \"-y\" },\n y: { field: \"no2\", type: \"quantitative\" }\n }\n})","pinned":true,"hidden":false,"mode":"ojs"}],"files":"$W32","stdlib":"1","titling":"auto"}