Reporting templates for 1000 Cities Challenge

[carlhiggs]

We have planned a couple of meetings for the software team @global-healthy-liveable-cities/software-spatial and study executive @global-healthy-liveable-cities/ghscic-study-executive to discuss considerations for formatting our reports -- specifically how we can get a basic version up and running for the 1000 Cities Challenge.

Here are the latest versions of our current reports for the example city of Las Palmas, generated with the latest-ish version of our software (4.2.1):

Drafts (default; if the publication_ready in study region configuration files is set to False)
English Español 简体中文

"Publication ready" (if publication_ready is set to True, the notifications about being a draft are removed)
English Español 简体中文

The discussions are focused on the city reports rather than the scorecards, the generation of which has been partially drafted but is planned to be implemented, later. The report and scorecard implementations will each require updating of code and layout to accommodate the policy audit tool once finalised (this may be in May 2023), although the extraction of policy results using the current draft has been prototyped. Inclusion of results using the updated policy audit tool is not expected to occur before June 2023, however the aim is to achieve a functional prototype by that time. This discussion will inform how the prototype we aim to produce by mid-June 2023 will look.

The topics for discussion in the meetings include:

• brief demonstration of resource generation using the current software (what is currently produced)
• Currently we use a 25 cities benchmark; what do you think should be done?
• How should density/connectivity thresholds be communicated?
• How should policy-related graphs and checklists be presented?
• What's not in the report that should be?
  • The report is currently 6 pages, but I suggest increasing to 8 or 12 pages to facilitate easy printing with saddle stitching binding (imagine two landscape A3 pages stacked and stapled in the middle for a cheap, easy A4 booklet)
  • So, we can have more space to include additional images, policy checklists, data listings, glossary, 15Ds framework. What would you include?
• Other reporting considerations

I will post the minutes for the two meetings below. Your contributions to the discussion as comments here are welcome!

[carlhiggs]

Spatial working group meeting - 2023-04-19

Attendees: Carl (CH; minutes), Eugen (ER), Jonathan (JA), Shirley (SL)

Currently we use a 25 cities benchmark; what do you think should be done?

In general, the team agreed that for the spatial indicator results we could make the default (plugin_comparison: False) be that no external comparison is made (eg. remove the dot and bar comparison from the access to amenities plot, and display within-city walkability distribution, and no 25-city annotation on policy plots).

However, we agreed that it would be good leave the option for users to set plugin_comparison: True, and so provide flexibility for users to customise with relevant comparisons for their own purposes (e.g. the Spanish team after analysing their cities could enter in the comparison values in the configuration in the indicators.yml file. This could then generate and display results in a similar way to the current reports, but with a user selected relevant comparison. The Global Observatory could use the 'no comparison' version, or otherwise determine what is the relevant report format for their official dissemination purposes, perhaps even generating this themselves from the user provided data.

Other thoughts:

• SL: Add reference to 25 cities report in introductory prose
• ER: Could include map of the 25 cities and show table with average values for indicators
  • CH (wondering while writing up): If we did this, on second page or appendix? Too much information maybe?

How should density/connectivity thresholds be communicated?

First, it was suggested that rather than display the percentage of population meeting thresholds in brackets, we use an upside down arrow to indicate it on the plot (like in policy rating plots).

However, Eugen then suggested, and their was consensus agreement, that rather than describe the percentage of population meeting these thresholds we display the mapped distribution and provide a description of why this is relevant and refer to the threshold in the description, allowing readers to interpret this themselves with regard to their local context.

It was also suggested by Eugen that we could include a histogram-like plot displaying the population distribution with the evidence based 'sweet spot' marked (like in the Lancet series infographic). However, Shirley was concerned that histograms could be over-complex for this report. It occurred to me that if we included a plot overlaying the straight density distribution (of intersections or population per sqkm within each 100m grid square) with the distribution of walkable neighbourhood density --- this could help make the distinction between these concepts more clear to the reader, with the help of a prose description, and show the relevance of the latter concept for promoting physical activity. Shirley makes a good point about the challenges of displaying information people can understand though (to some degree the report/scorecard distinction covers this though).

How should policy-related graphs and checklists be presented?

• If not assessed (default), display 'Not assessed' (on checklists that is in brackets after checkbox title)
• We agreed on removing the 25 city income category checklist column

What's not in the report that should be?

• CH: 11Ds framework diagram
  • simplified, without green highlighting
  • I thought could include early in the report, to provide context.
  • Perhaps there could be hyperlinks on different concepts that could link to GOHSC to read more, eg about 'Disaster mitigation' etc)
• ER & SL: glossary/appendix with a simple table, w/ 11Ds in easy to understand terms
  • suggested 11Ds should be in appendix, so people see their results first and can see more information if interested)
  • personally, I'm not sure of the appendix idea, unless we expand to 12+ pages
  • I think the scorecard is there for the 'here are the results' for quick viewing; the report then should guide people through them, while not being over-technical (and if we have an appendix, maybe that's getting technical? Could hyperlink to detail on GOHSC).
  • There will be a seperate analysis report generated with full technical details (I am working on this); that's a good place for appendices etc.

Other reporting considerations

• ER & SL suggested the current frontmatter (p2) should go to end of report.
• CH: Regarding including citations (as per SL suggestion), could trial using numerical superscript citations, with references listed at end; if possible, numbers could hyperlink to DOIs etc

[carlhiggs]

Study executive group meeting - 2023-04-27

@global-healthy-liveable-cities/ghscic-study-executive

Attendees: Carl (minutes), Deb, Ester, Eugen, Jonathan, Melanie
(oh, what a pain; I wrote a detailed summary yesterday, but got distracted with other tasks and e-mails and forgot to post it and lost it! now writing it again... sorry it will be briefer; I'll try to cut to chase than report on nuances)

Currently we use a 25 cities benchmark; what do you think should be done?

In general, we plan to

• by default remove comparisons (as detailed in above post)
• allow them to be configured to be displayed, optionally for users' own needs, e.g.
  • using the published '25 cities' benchmarks, or
  • a set of relevant benchmarks derived from users own processed results, e.g. the collection of Spanish cities
• the GOHSC executive can determine the comparison to be displayed for official publication

Regarding the plot of the spatial distribution of relative walkability, ML and DS felt the 25-cities comparison was still relevant to ensure that cities with overall poor walkability don't appear better than they should. It was suggested that this comparison be retained, and an addition information box provides more details on this comparator reference and link to the Lancet series.

I propose this works as follows:

• if a comparison is configured, summary text is also provided to explain this comparison and displayed in a box (e.g. 25 cities comparison will be provided
• comparisons are configured seperately for different plots
• by default comparisons will be disabled for all plots except walkability (unless we later decide it too should be disabled by default)
• if comparison is turned off altogether, then the comparison explanation box could contain some other local walkability statistics, to contextualise what is displayed. Otherwise, the box provides comparison explanation text.

How should density/connectivity thresholds be communicated?

• there was enthusiasm for the proposal of an infographic-like histogram show distribution of densities and threshold mark, and updated prose explanation (should be simpler, easier to understand), proposed above; we will trial this.

How should policy-related graphs and checklists be presented?

• there will be new measures, which will require more space
• we'll take off the 25-city comparisons
• as per above, if something hasn't been assessed there will be a clarification: "(Not assessed)"
• checklists will change a bit
  • to reflect the new fields in the revised policy document
  • be simplified to display less nuance (e.g. just ticks or crosses, if possible)
    • although if some items haven't been assessed (eg if deemed by policy auditor to not be relevant; e.g. for some items like dust controls, some have suggested it doesn't apply, etc; we may disagree, but it will happen that some items aren't completed), perhaps we need to display for that item not assessed or a hyphen

What's not in the report that should be?

• We will include hyperlink text to explanations on GOHSC to serve as a glossary/appendix. Things like 11Ds, or interlations between policy aspects can be explained there.

• It was suggested that 11Ds framework may not be appropriate language for the users of this report, and the current approach is appropriate. Can explain 11Ds linkages, and emphasise more about integrated urban planning, via hyperlinks to more detail on GOHSC.

• It was suggested that instead of a prose paragraph summary, users could provide 'key points'.

  • This can also be used to contextualise findings, and users should be allowed some flexibility here to ensure the findings are made relevant for their city
  • If we do this, Headings for points could be
    • City strengths
    • Aspects that need attention
    • Surprising results
  • Technically, we don't need to change anything here; we could simply recommend users to use this format, but provide them the flexibility to do what they need to do to appropriately contextualise findings for their city. The main thing is, that they do this.

• A city context box will be required to provide brief (< 50 characters) clarifications for key aspects, e.g.

  • Regional characterisation
  • Socio-economic conditions
  • Weather
  • Topography
  • When the city was founded

• There should be an explanation for how the study region was defined

  • This should be very brief and high level (e.g. 'built up urban area'/'mancha urbana'), and can direct readers to the analysis report for details

Other reporting considerations

• We will aim for 8 pages
• There will need to be more spacing around edges to allow for printing (e.g. more of a gap for text, to be safe)
• We should make a mock up of the report before coding it
• The more changes we make from the current form/format, the more challenging it will be to implement and longer it will take