9. Frequently Asked Questions (FAQ)
🔹 What does the software do?
The GHSCI software can be configured to calculate and report on policy and spatial indicators for healthy and sustainable cities in diverse contexts globally. The core set of spatial indicators is calculated for point locations, a small area grid (e.g. 100m), and overall city estimates. Optionally, indicators can also be calculated for custom areas, like administrative boundaries or specific neighbourhoods of interest. In addition, CSV files containing indicators for area summaries and the overall city are also generated, omitting geometry. Metadata and data dictionaries are generated to accompany the data, along with reports in multiple languages.
The default core set of spatial urban indicators calculated includes:
- Urban area in square kilometres
- Population density (persons per square kilometre)
- Street connectivity (intersections per square kilometre)
- Access to destinations within 500 meters:
- a supermarket
- a convenience store
- a public transport stop (any; or optionally, regularly serviced)
- a public open space (e.g. park or square; any, or larger than 1.5 hectares)
- A score for access to a range of daily living amenities
- A walkability index
The tool can also be used to summarise and visualise policy indicators data collected using the 1000 Cities challenge policy checklist tool.
The resulting city-specific resources can be used to provide evidence to support policymakers and planners to strengthen urban policy, target interventions within cities, compare performance across cities, and when measured across time can be used to monitor progress towards achieving urban design goals for reducing inequities. Moreover, they provide a rich source of data for those advocating for disadvantaged and vulnerable community populations.
Generated outputs include:
- Summary of configuration parameters used for analysis (.yml file)
- Processing log detailing the analyses undertaken (.txt file)
- Geopackage of indicator results and spatial features including points and areas of interest and pedestrian network (.gpkg)
- CSV files for indicator results (.csv)
- Data dictionaries (.csv and .xlsx files)
- ISO19115 metadata (.xml and .yml files)
- Analysis report (pdf)
- Policy and spatial indicator report, optionally in multiple languages (.pdf)
- Figures and maps, optionally in multiple languages (.jpg)
The software is designed to be used by local experts as part of multi-disciplinary teams participating in the 1000 Cities Challenge; but anyone (e.g. students, enthusiasts) can use the open-source software.
🔹 How to amend configuration details if the web application advises that configuration is not yet complete for a new study region
🔹 Avoiding Errors and Running Configuration Analysis Smoothly
- Follow along with the provided example analysis using Jupyter Lab, as guided in this video.
- Copy the example configuration file and example analysis notebook files show in the example video linked above, and adapt them as a starting point for your city.
- Try running the analysis in a notebook using the provided Jupyter Lab software environment, or using Python, within our GHSCI Docker software environment. When run in this way, important messages or warnings may guide errors in configuration that may not appear in the web app.
- Use forward slashes
/instead of backslashes\when writing file paths, and enclose file paths in quotation marks, like"relative/folder/path/to/a/file.txt". - If using the GHSCI web application and modifying or adding a new configuration file, refresh the study region list using the button on the right hand side above the table or exit and restart the application to ensure the latest version of your region's configuration file is used.
🔹 Check the log file
Sometimes things can go wrong, and you might get a message advising you of this. For example, an entry in the region configuration YAML might be missing a space after a colon character (for example, :true instead of : true) or a path to data may have a typographical error. The nature of warnings will depend on how you are running the software. However, if your configuration file has successfully been loaded and analysis has commenced, the most informative place to look is the text file log that can be found in the data output folder for your study region. Open this file in a text editor and scroll to the end to find the point where things may have gone awry.
🔹 Check configurations
If the data output folder for your study region hasn't been created or doesn't contain an analysis text log after attempting to run the analysis workflow, it is likely that an error in your configuration file has prevented it being successfully loaded. Check to see if an error was displayed, e.g. advising that configured data files could not be located at the paths specified. Consider comparing your study region configuration with the provided example and see what might differ. A small error could stop the file from being successfully loaded, but in many cases, there are clues given as to where to find and correct this.
Configuration files are easier to read and edit in a text editor that provides syntax highlighting. For example, you can view and edit the YAML files using the provided Jupyter Lab interface in your web browser. Alternatively, there are software options such as VS Code or Notepad++.
🔹 What if things go wrong?
Use the correct coordinate reference system (units in metres);
Ensure your project is using a projected coordinate reference system (CRS) with units in meters. If this step is missed, errors may not be immediately obvious, but data retrieval or mapping may fail (e.g., your study region may appear empty and fail to retrieve OpenStreetMap data).
Double-check that the configured data is the correct data set
Verify that each data set you've configured is the intended one for your analysis. For example, if you need urban region boundaries, ensure you’re using a compatible geopackage like the GHSL UCDB, rather than another data set like population data, which may not suit your needs.
Ensure data represents the correct time period
Be mindful that your data should align as closely as possible with the time period you aim to represent for your region of interest. For example, if your analysis aims to represent 2024, then using older population data or urban boundaries (for example, opting to use the R2019a Global Human Settlements Layer's Urban Centres Database for city boundaries, which represents urban regions in 2015) may lead to unintended inaccuracies and limit the relevance of your findings.
Follow configuration patterns carefully
Observe the recommended configuration patterns described in the example configuration file. Mistakes, like placing GTFS data in the wrong directory or not structuring folders by city/region as directed, can prevent files from loading or being read correctly.
🔹 What if memory errors or storage issues occur during analysis?
Some analyses, especially for larger cities, may encounter memory allocation issues with Python, Docker or PostgreSQL. This can cause errors during processing, such as:
sqlalchemy.exc.OperationalError: (psycopg2.errors.DiskFull) could not resize shared memory segment "/PostgreSQL.3478590822" to 33554432 bytes: No space left on device
If this error occurs, it's likely not about the user's own disk space but rather how much memory has been allocated for PostgresSQL in our Docker file. If this error occurs, it should be increased for analysis for this city to be successful. To solve this follow these steps:
-
In Docker Desktop, delete the existing containers (noting this will mean databases for previously processed cities will be removed unless backed up).
-
Open docker-compose.yml (located in the root folder of the software downloaded) in a text editor and add in an entry like
shm_size: 2gunder thepgroutingsection, just like it also appears under theghscisection. -
Re-launch the software (e.g. By entering
bash ./global-indicators.shif using a Mac/Linux, or./global-indicators.baton Windows).
🔹 What are the 1000 Cities Challenge policy indicators?
The policy indicators for the 1000 Cities Challenge assess the presence and quality of a wide range of urban and transport policies that contribute to creating healthy and sustainable urban environments.
🔹 Can I just generate policy indicators for my city, or do I also need to generate spatial indicators?
You can choose to generate policy or spatial indicators, or both types of indicators. The 1000 Cities Challenge has indicator reports for each type of indicator, as well as the combined policy and spatial indicators.
🔹 Is the policy checklist available in languages other than English?
No, currently we only have an English version of the policy checklist. However, we plan to translate it into other languages in future. If you are interested in helping with translations, please contact [email protected]
When filling in the checklist, please translate policy details into English, if required.
🔹 What levels of government policies can I include in the policy checklist?
The checklist can be applied to any jurisdiction (e.g. local, metropolitan, or regional government), as relevant to your city. However, the Global Observatory of Healthy and Sustainable Cities aims to include the whole metropolitan area of cities, wherever possible. Therefore, we recommend:
- applying the checklist to the level(s) of government responsible for the whole metropolitan area, and/or which affect the majority of the metropolitan population.
- if you are only assessing a smaller administrative unit/jurisdiction within a larger metropolitan area, please clearly indicate this is the
Collection detailstab, and explain why. - If multiple levels of government are relevant for your city, include policies for all relevant levels of government in the same checklist.
🔹 What do I do if multiple levels of government are relevant for your city?
This is the case for many cities. Include policies for all relevant levels of government in the same checklist. You can indicate which policies belong to which levels of government throughout the policy checklist.
🔹 How do I find relevant policy documents?
Data collection will require identification, retrieval, and assessment of the content of multiple policy/legislative documents. Use your existing knowledge of the current urban policies/guidelines/legislation for your city, search government websites or policy repositories, and/or seek advice from policymakers.
Tip: Use the indicators and measures included in the policy checklist as a guide when identifying relevant government sectors and searching for relevant documents.
🔹 How do I find relevant policy content within a policy document?
Search the identified policy documents for relevant content. Look at documents' Table of Contents; or use CTRL+F to find content using keywords (and synonyms) from the policy checklist measures and principles.
🔹 Are there examples of completed policy checklists?
At the top of the Policy Checklist, there are examples of how to fill it in. You can also see examples of filling in the policy checklist in the recorded training sessions:
🔹 What is a measurable policy target?
A measurable policy target is a measurable quantitative standard or threshold that may include a delivery timeframe. An example of a measurable target related to housing density is: ‘Increase average gross densities of development within activity centres and transit corridor catchments from 15 to 25 dwellings per hectare to 35 dwellings per hectare’.
🔹 How do I know if a policy target is an evidence-informed threshold (Columns L & M in the policy checklist)?
In Column L, for all policies that include a measurable target, please record if the target is an evidence-informed threshold. Base your assessment on accepted standards and research evidence, to the best of your knowledge. If unsure, select unclear, and this can be checked during the validation step. Leave Columns L & M blank where the policy has no measurable target.
🔹 What do I do if there is more than one policy document applicable to a particular principle?
List multiple policies by inserting and completing new rows below that principle, as required. To do this, right-click the number of the row below where you require a new row and select Insert.
🔹 What do I do when I have completed the policy checklist?
The next step is to validate the checklist with the help of the 1000 Cities Challenge team. Email your completed Policy Checklist to [email protected]. You will then be notified of the local data validation process.
🔹 Why does the policy report not generate as intended?
The policy checklist Excel file is a template, and any modifications (for example, unmerging cells) can have result in issues with both analysis, formatting, and successful generation of a policy report.
When adding new rows to record additional policies that have been reviewed, ensure that existing rows do not unmerge. To do this, right-click on the row number of an existing row within the indicator (Column A) that you are adding a new row, and click insert. This should add a new row within that indicator, without unmerging existing cells.
Policy presence is scored as the number of policy checklist requirements aligned with policies.
Policy quaility is scored accounting for the degree to which identified policies are measurable and aligned with healthy cities principles and evidence.
A quality score is first given based on whether an identified policy has a measurable target:
- No policy exists = 0
- Policy exists but no measurable targets = 1
- Policy exists with (at least one) measurable target = 2
The initial score is then multiplied by a modifier, according to alignment and consistency with healthy cities principles and evidence:
- Consistent with healthy cities principles/evidence = 1
- Mixed, partly inconsistent with healthy cities principles/evidence = -0.5
- Inconsistent with healthy cities principles/evidence = -1
🔹 What does validation of the policy checklist involve?
Someone on the 1000 Cities Challenge team will check your completed policy checklist and provide feedback. You may also want to get someone with local knowledge of your city (e.g. a policymaker or planner) to check the policy checklist for you.
🔹 How do I generate reports after completing the policy checklist?
A Policy Indicators Report or combined Policy and Spatial Indicators Report (if you have also completed spatial indicators) can be generated through GHSCI software. Please contact the 1000 Cities Challenge team at [email protected] for support using the GHSCI software, or we can assist with generating Reports for you.
🔹 How do I get my city’s policy indicators included in the Global Observatory of Healthy and Sustainable Cities?
Send the finalised Reports for your city to [email protected], for inclusion on the Global Observatory website.
🔹 Who do I contact for help with filling in the policy checklist?
You may find answers to your questions in the recorded training session videos above or visit the Resources page at Global Observatory of Healthy and Sustainable Cities.
🔹 What to Consider if a Large Study Area Fails to Run Successfully?
-
Insufficient Memory
Running large study areas requires substantial memory. For example, analyzing the Los Angeles Metro network (over 1 million edges) typically demands at least 32 GB of RAM. If you don’t have enough, consider reducing the chunk size to optimize performance. Thechunk_sizecan be found in theconfig.ymlfile; follow the comments in the file. -
Hardware Issues
Hardware problems, such as faulty RAM, may only surface during intensive tasks. Ensure your hardware, particularly RAM, is functioning correctly before troubleshooting further. -
System and Docker Updates
Unexpected issues can arise with large study areas. Make sure your operating system and Docker Desktop are fully updated before beginning the analysis. To download the latest version of Docker Desktop, visit the official site or check updates in your existing software. -
Anticipate Time Consumption
Step 11, i.e., network-building for neighbourhood analysis, often takes the longest in large urban areas. Consider running smaller test areas first, and plan to leave your machine running overnight for the full analysis.
🔹 How long does it take to run the spatial analysis? In general, collecting and configuring resources required for analysis along with the associated metadata and subsequent validation of analyses are the most time-intensive steps. The time taken to run analyses for configured study regions will vary depending on city size and density of features, and the specification of the computer running analyses. A minimum of 8GB of RAM is recommended; in general, the more RAM and processors available, the better. It is possible that lower specification machines will be able to perform analyses of smaller urban regions. The provided example city of Las Palmas de Gran Canaria should take about 8 minutes to run on a standard laptop, however, some larger cities may take a number of hours to process.
🔹 Drop a study region database and restart an analysis
If you have commenced an analysis but want to drop any existing results, for example if you have changed your study region configuration to address issues such as the above, you can do this using Python. At the GHSCI command prompt, enter 'Python', and the following:
import ghsci
r = ghsci.Region('your_study_region_name')
r.drop()
If you have any connections to this region database active (for example, in Jupyter Lab or using QGIS or ArcGIS), close these.
You will be asked if you really want to do this and prompted to confirm.
Once the database has been removed, you will still have to manually remove any files and folders in the study region folder at process/data/_study_region_outputs/your_study_region_name, or alternately, rename that folder (perhaps using the date at which it was current) as a backup.
In addition to English, on-going efforts are being made to provide validated translations for our reporting templates since these were updated in 2024. We are aware of current issues displaying some non-latin fonts featuring right-to-left text and Devaganari conjuncts, features that we hope to support in the near future.
The languages available for use with the current reporting templates are:
- English (Validated)
- Arabic (عربي; Draft translation only)
- Catalan (Català; Validated)
- Chinese - Simplified (简体中文; Validated)
- Chinese - Traditional (繁體中文; Validated)
- Croation (Hrvatski; Draft translation only)
- Czech (Čeština; Draft translation only)
- Danish (Dansk; Draft translation only)
- Dutch (Nederlands; Draft translation only)
- Finnish (Suomi; Draft translation only)
- French (Française; Draft translation only)
- German (Deutsch; Draft translation only)
- Greek (Αγγλικά; Draft translation only)
- Hausa (Hausa; Draft translation only)
- Hindi (हिंदी; Draft translation only)
- Indonesian (bahasa Indonesia; Draft translation only)
- Italian (Italiano; Validated)
- Japanese (日本語; Validated)
- Korean (한국인; Draft translation only)
- Māori (Māori; Draft translation only)
- Nepali (नेपाली; Draft translation only)
- Persian (فارسی; Draft translation only)
- Portuguese - Brazil (Português do Brasil; Validated)
- Portuguese - Portugal (Português de Portugal; Validated)
- Spanish - Latin America (Español de Latinoamerica; Validated)
- Spanish - Spain (Español de España; Validated)
- Tamil (தமிழ்; Draft translation only)
- Thai (ภาษาไทย; Draft translation only)
- Turkish (Türkçe; Validated)
- Ukrainian (Український; Draft translation only)
- Vietnamese (Tiếng Việt; Validated)
🔹 Check for issues
Other users or the developers themselves may have come across the issue you are experiencing and posted a question or resolution for this on our software code repository. You can browse, query or add a comment to open or closed issues here.
🔹 Report a bug, request a feature, or contribute to the project
Perhaps you have come across a use case or data format that we haven't considered or accounted for. You can report a bug or make a feature request online here. To ensure our community can help you, try to provide as much contextual detail as possible. This can include copying text from your log file and configuration file(s) as appropriate; often the solutions will be found by understanding what is contained in these documents.
Contributions are welcome! Some advice on doing this is found here.