Experience evaluation GHSCI v4.4.10

[dapugacheva]

Experience evaluation report of ghsci v4.4.10, main branch

The test was conducted on an Apple M2 Pro chip, 16GB RAM machine. Overall, The analysis worked as intended for the example city Las Palmas. Below are considerations regarding the user experience when running software in the Web App and Jupyter Lab.

Web App

Overall, the process went smoothly on the web app application for the example city. It took 20 minutes to run.

Key things to consider for improvements:

• Add step-by-step guidance and description of every step starting from the Running the provided examples step from GitHub.
  • Simple descriptions and step-by-step guidance that is provided on GitHub or in Jupyter Lab are helpful for guiding the process. To avoid moving back and forth from the website/Github guidance to the web app application tab, it would be helpful to have the same description on the web app; for example, in the empty space of the interface on the right side of the web application tab.
• Correct the PDF reports folder name from web_reports to reports (since the folder is called 'reports') in the website guidance in the Generate chapter.
• Add instructions on how to properly end the process. Steps such as exit the app and stop ghsci container in docker. It is important for non-programmers to clarify this.
• Overall, the guidance requires some sort of conclusion and/or next steps at the end of the before Citations to facilitate future use of the software.
  • For example, it could be instructions on configuring other study regions and guidance on the data collection.
• It would be valuable to see the interactive maps of indicators like the walkability index in the Jupyter Lab.

Jupyter Lab

GitHub is easy to follow for Jupyter Lab users. It is also more interactive and customizable (such as More advanced usage and mapping part). The process took about 15 minutes to run on the MacBook Pro Apple M2 Pro chip. ARM64 processor compatibility issue to resolve: The requested image's platform (linux/amd64) does not match the detected host platform (linux/arm64/v8) and no specific platform was requested 0.0s.

Key things to consider for improvements:

• Display the map of the example study region in the Jupyter Lab as in the Web app.
• Add interactive maps of the example study region (configure output) and a map with pop-up window of indicators (analysis output).
• Fix the docker ARM64 processor compatibility. AMD64 image cannot be identified and displayed in the Jupyter Lab.
• Edit the file path under the Sensitivity analysis description to <process/configuration/regions/example_ES_Las_Palmas_2023.yml>
• Add a color palette parameter to the r.choropleth function so users might adjust the color of the map.

The report might be updated with new feedback as we continue to use the software.

[ruoyuch]

Daria's comments cover most points well. I am adding some of my points here.

My test is conducted on an Apple 2020 MacBook with an Intel i5 CPU, Intel Iris Plug Graphics (not an actual GPU), and 16 GB RAM. The MacOS version is Sonoma 14.0.

General comments on the instructions

1. Current instructions for Windows/MacOS/Linux are mixed up; it would be better if we had a button on the corner of the website to select Windows/MacOS/Linux and filter out the instructions for other operation systems.

• we will have a clearer and more separate paragraph in the "Software set up" section.

2. I got a bit confused in the beginning part when the requirement of downloading the docker popped up. I suggest we have a "checklist" of what to download before starting the demo—download the docker, download the software, and so on.

• we will have a checklist in the beginning.

Web App

The Web App is intuitive for me. The process is generally easy to follow. The "analysis" process took roughly 4~5 minutes on my computer for the Las Palmas example.

1. Only one of the URLs popped up works for me; I cannot get the interactive website via the other one. This might be a bit confusing for a first-time user.

• we will try to disable the token for docker.

2. In a full-screen (1920*1080) setting, the webpage is not centered; it only uses the left 60% of my screen, which could be a little weird.

• this comment should be ignored after discussion, it is better to have a half-window to follow the instructions.

3. Every time I use the "analysis" tool, there is a chance of the message "connection lost" showing up. Sometimes, it will be "reconnected" very quickly; sometimes, I can only shut down the whole thing and open up again. I suggest it would be better to let the user know what to do when an error pops up.

• Ruoyu will try to replicate this issue here.

4. It would be helpful if some of the mapping results could be visualized interactively in the web app.

• we will try to add a mapping function to the program.

5. Is it possible to make the pdf report available directly on the webpage? For example, people can have a "download (English)" button after pressing the generate button. People who do not have basic coding skills could easily lose their way when trying to find the embedded data folder.

• we will create a "copy and paste" or "source linkage" button on the website.

Jupyter Lab

The Jupyter Lab is more useful in a sense of better flexibility. The "analysis" process took roughly 4~4.5 minutes on my computer for the Las Palmas example.

1. I am wondering whether it is possible to switch between Jupyter Lab and Web App without shutting down the terminal. I cannot do this by typing the exit command. Also, every time, I need to shut down both the Docker and Terminal before I can rerun the software in a Jupyter Lab.

• this is because the docker container cannot be switched. We will try to have two different commands to run the container in different ways—rather than having the same command to initiate the program and choose Web App/Jupyter Notebook with another command.

2. Same issue here that only one of the URLs works.

• we will try to disable the token for docker.

[dapugacheva]

Hi, @carlhiggs we discussed the modifications proposed above with @gboeing and decided to proceed with the following tasks below. Some of them have solutions that are ready for pull requests, some will require more time. Let us know if you have any comments on that.

A. Web App

1. Add instructions for the web app. There are three possible solutions:
   a. Add instructions from the README file on the right side or/bottom of the webpage (see image below).

   Image

   

   b. Add pop-up floating windows as short comments for beginner users for each step.
   c. Do not add instructions to the web app. Instead, recommend having multiple windows open with instructions on the left and a web app window on the right to view both side-by-side.
   @dapugacheva @rychennn

2. Create a "copy and paste" or "source linkage" button on the web app to make it easier to download the .pdf report.
   Add the mapping function to the web app. @rychennn

3. Add the mapping function to the web app. @rychennn @dapugacheva

B. Jupyter Lab and Software set up on GitHub:

1. Add the fill_color parameter to the r.choropleth function in the ghsci.py (also consider adding fill and line opacity). @dapugacheva
2. Add instructions on how to exit the software to the README file after the description of the Compare function and before Citations:
   “Exit the web application (click the button in the top right-hand corner) or type exit in the terminal window before closing the web app browser window or go to File -> Shut Down in Jupyter Lab. Our website provides detailed instructions on how to configure a new study region file https://global-healthy-liveable-cities.github.io/software/#Details and what input data is required https://global-healthy-liveable-cities.github.io/software/#Data.” @dapugacheva
3. Correct text errors in the Jupyter Notebook instructions: edit the file path under the Sensitivity analysis description to process/configuration/regions/example_ES_Las_Palmas_2023.yml @dapugacheva

C. Instructions on the website:

1. Add a clearer and more separate paragraph in the "Software set up" section about how to set up the software in different operation systems, i.e., Windows/MacOS/Linux. @rychennn
2. Provide a checklist in the beginning on what to download before starting the demo. @rychennn
3. Add the same instructions described above (B.2) to the website. @dapugacheva @rychennn

D. Docker Files @rychennn @dapugacheva

1. Add the following code to the docker-build.sh file to fix the ARM/AMD image error docker buildx build --push --platform=linux/amd64,linux/arm64 -t globalhealthyliveablecities/global-indicators .
   • citations from https://docs.docker.com/build/building/multi-platform/, https://www.docker.com/blog/faster-multi-platform-builds-dockerfile-cross-compilation-guide/, osmnx doker
2. Disable the token for the docker to make sure that only one URL pops up and works well.
3. Try to have two different commands to run the container in different ways (web app and Jupyter lab)—rather than having the same command to initiate the program and choose Web App/Jupyter Notebook with another command.

[carlhiggs]

Hi @dapugacheva , Happy for you to trial these things. From memory, the multi platform Docker build isn't straightforward --- previously had issues with this, but it will be good to explore that so those with newer Apple chips like yourself aren't disadvantaged. I drafted an updated Docker image in a new branch but haven't had opportunity to test it extensively. It would be good to work off that rather than main branch, and if you could confirm the updated software packages work that would be great. Some newer versions of Pandas introduce issues, and the GUI framework is frequently updated; the new branch aims to update packages and code to deal with these things. Eugen is still working on the updated report layout, so I think best to leave enhancements branch on hold. I would consider working with a branch off the newer one I created. Hope this helps, and appreciate your work. I'll be travelling for coming week so may not be in position to respond. Cheers, Carl

…

On Thu, 15 Feb. 2024, 11:13 Daria Pugacheva, ***@***.***> wrote: Hi, @carlhiggs <https://github.com/carlhiggs> we discussed the modifications proposed above with @gboeing <https://github.com/gboeing> and decided to proceed with the following tasks below. Some of them have solutions that are ready for pull requests, some will require more time. Let us know if you have any comments on that. A. Web App 1. Add instructions for the web app. There are three possible solutions: a. Add instructions from the README file on the right side or/bottom of the webpage (see image below). Image Screenshot.2024-02-09.at.5.27.32.PM.png (view on web) <https://github.com/global-healthy-liveable-cities/global-indicators/assets/142947564/2c2f1024-b92a-4986-80ab-239a3ba7eadd> b. Add pop-up floating windows as short comments for beginner users for each step. c. Do not add instructions to the web app. Instead, recommend having multiple windows open with instructions on the left and a web app window on the right to view both side-by-side. @dapugacheva <https://github.com/dapugacheva> @rychennn <https://github.com/rychennn> 2. Create a "copy and paste" or "source linkage" button on the web app to make it easier to download the .pdf report. Add the mapping function to the web app. @rychennn <https://github.com/rychennn> 3. Add the mapping function to the web app. @rychennn <https://github.com/rychennn> @dapugacheva <https://github.com/dapugacheva> B. Jupyter Lab and Software set up on GitHub: 1. Add the fill_color parameter to the r.choropleth function in the ghsci.py (also consider adding fill and line opacity). @dapugacheva <https://github.com/dapugacheva> 2. Add instructions on how to exit the software to the README file after the description of the Compare function and before Citations: *“Exit the web application (click the button in the top right-hand corner) or type exit in the terminal window before closing the web app browser window or go to File -> Shut Down in Jupyter Lab. Our website provides detailed instructions on how to configure a new study region file https://global-healthy-liveable-cities.github.io/software/#Details <https://global-healthy-liveable-cities.github.io/software/#Details> and what input data is required https://global-healthy-liveable-cities.github.io/software/#Data.” <https://global-healthy-liveable-cities.github.io/software/#Data.%E2%80%9D>* @dapugacheva <https://github.com/dapugacheva> 3. Correct text errors in the Jupyter Notebook instructions: edit the file path under the Sensitivity analysis description to process/configuration/regions/example_ES_Las_Palmas_2023.yml @dapugacheva <https://github.com/dapugacheva> C. Instructions on the website <https://global-healthy-liveable-cities.github.io/software/#Generate>: 1. Add a clearer and more separate paragraph in the "Software set up" section about how to set up the software in different operation systems, i.e., Windows/MacOS/Linux. @rychennn <https://github.com/rychennn> 2. Provide a checklist in the beginning on what to download before starting the demo. @rychennn <https://github.com/rychennn> 3. Add the same instructions described above (4) to the website <https://global-healthy-liveable-cities.github.io/software/#Compare>. @dapugacheva <https://github.com/dapugacheva> @rychennn <https://github.com/rychennn> D. Docker Files @rychennn <https://github.com/rychennn> @dapugacheva <https://github.com/dapugacheva> 1. Add the following code to the docker-build.sh file to fix the ARM/AMD image error docker buildx build --push --platform=linux/amd64,linux/arm64 -t globalhealthyliveablecities/global-indicators . - citations from https://docs.docker.com/build/building/multi-platform/, https://www.docker.com/blog/faster-multi-platform-builds-dockerfile-cross-compilation-guide/, osmnx doker <https://github.com/gboeing/osmnx/blob/main/environments/docker/docker-build.sh> 2. Disable the token for the docker to make sure that only one URL pops up and works well. 3. Try to have two different commands to run the container in different ways (web app and Jupyter lab)—rather than having the same command to initiate the program and choose Web App/Jupyter Notebook with another command. — Reply to this email directly, view it on GitHub <https://github.com/global-healthy-liveable-cities/global-indicators/issues/375#issuecomment-1945120895>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ADDCCMTT3X37PRNIX5M6A53YTVHMPAVCNFSM6AAAAABCQTGM7WVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMYTSNBVGEZDAOBZGU> . You are receiving this because you were mentioned.Message ID: <global-healthy-liveable-cities/global-indicators/issues/375/1945120895@ github.com>

[carlhiggs]

Hi @dapugacheva and @rychennn, regarding,

D. Docker Files @rychennn @dapugacheva

1. Add the following code to the docker-build.sh file to fix the ARM/AMD image error docker buildx build --push --platform=linux/amd64,linux/arm64 -t globalhealthyliveablecities/global-indicators .

I previously tried this and had some issues, presumably related to package compatability (as per e-mail I just sent); notes are here, in case you experience something similar:
https://github.com/global-healthy-liveable-cities/global-indicators/issues/172#issuecomment-1418540797

But, fingers crossed with updates to dependencies since then (about a year ago), perhaps things may just work now!

[carlhiggs]

(apologies --- I was typing thinking I was on another window and accidentally modified the assignments, clearing all, then accidentally clicked on me

Since I'm commenting (sorry for confusion there!) I've been looking into the Docker build since there were new dependabot alerts, and had a go with the arm64 architecture, possibly with some success. Just pushed the commit now (I was typing the commit message when I accidentally did the above when i flicked here to reference issue numbers).

Anyway -- fingers crossed we are getting closer to arm64 support; thank you for raising this issue again.

[eugenrb]

I am adding a common error encountered by some Windows users from the Mexico team when trying to launch Docker after installation.

"Group Membership Error"

Solution:

• Log in to Windows as Admin
• Run Computer Management as an administrator and navigate to Local Users and Groups > Groups > docker-users. Right-click to add the user to the group.
• Log out and log back in for the changes to take effect.

This solution only works if you have admin access. Users may need IT support to solve the issue if the computer is not personal equipment.

[gboeing]

I am adding a common error encountered by some Windows users from the Mexico team when trying to launch Docker after installation.

@eugenrb Did you reboot after installation? Depending on how you installed, the user may be auto added to the docker-users group after a reboot.

If that doesn't work, the solution may be simpler. From an admin-privileged command prompt run:

net localgroup docker-users "your-user-id" /ADD

or

net localgroup docker-users DOMAIN\username /add

[eugenrb]

This happened to me on my UT laptop. Since I have admin credentials, I could fix it using the steps I shared. However, someone from the Mexico team could not resolve the issue because they used a university computer without admin credentials. In that case, per university policies, they could not change even with IT support. It may be worth adding a note that yo may need admin credentials to install docker.

[gboeing]

It may be worth adding a note that yo may need admin credentials to install docker.

Yes indeed. Also, this looks well-documented in the Docker Desktop windows install instructions, so we should also be pointing users at those instructions if we're not currently.

[jiyoon0120]

I run the software on a ThinkPad with Windows 10, with an AMD Ryzen 7 PRO 4750U with Radeon Graphics 1.70 GHz and 16 GB RAM.
There are some repeated comments - below Web App no.1 and Instructions on the website no.1

Web App

1. When running the software by tying ‘ghsci’ in the terminal, it says ‘NiceGUI ready to go on http://localhost:8080/, and http://172.18.0.3:8080/’.
   The first link connects me to the software but the second link ‘http://172.18.0.3:8080/’ is not working.
   -> remove the second link

2. On the first screen of the software, the ‘SELECT OR CREATE A NEW STUDY REGION’ is located at the top of the map.
   -> It would be better to place the information near the list of study regions at the bottom.

3. It was confusing how to select a configured study region because there was no check box or similar indicator.
   -> Create a box figure next to the list of study regions

4. It seems like there is no unselect function by clicking the selected region. Unselecting was only working when I selected different regions.
   -> Create an unselect function

5. After performing the analysis and generating results, I wouldn’t have known about the pop-up summary that appears by clicking a region on the map without the instruction.
   -> There should be an icon or some information within the software that indicates the presence of a pop-up summary

6. In the COMPARE function, the region already selected in the ‘Study Region’ is still shown in the list of compare region.
   -> Selected ‘study region’ could be removed from the drop-down menu for selecting a comparison by creating a dynamic drop-down list.

Instructions on the website:

1. “The PDF reports (Figures 8 and 9) are located within the folder _web reports, while the maps and images generated for use in that report (Figure 10) are located in the figures folder.”
   -> Change the name of the folder to ‘reports’

2. “select the ES_Las_Palmas_2023_test_not_urbanx region from the comparison drop down menu and click Compare study regions to generate a comparison CSV in the example study region’s output folder (process\data_study_region_outputs\example_ES_Las_Palmas_2023) and display a table with side-by-side comparison of the overall region statistics and indicator estimates in the app window:”
   -> There are two buttons on the software. ‘VIEW COMPARISON’ and ‘EXPORT COMPARISON’ but not ‘Compare study regions’.

[carlhiggs]

Hi @jiyoon0120, thank you for having a look at the software.

Can I just check, which version of the GHSCI software and Docker image are you running? Some of the aspects you've commented on sound like things we have changed, so before we look to plan what amendments might be made, I just want to check they haven't already been.

We previously made changes to address how the URLs appear when launching the app, as seen in the current version of the software (4.6.0) --- although I accept its possible, things may appear differently on different user systems, its worth checking in case you might be using an earlier version before we have made some changes.

For example, the instructions for accessing the GHSCI app are considerably simplified, as in below snippet:

And reports are generated to a folder 'reports' already:

I haven't been through all of your points yet sorry --- I'm working across multiple tasks --- but if you could just double check if you are using the current version of the software, and if not consider checking in case any of these aspects have already been addressed that would be really useful.

Where issues remain, please feel welcome to contribute suggested modifications to code to address them. Pull requests are welcome!

[carlhiggs]

Re selecting a study region, the reason it is written above the map is that users who have processed study regions already can select a study region by clicking on the map, rather than using the table --- e.g. for Las Palmas:

The record in the table is highlighted when clicking on the map study region. Open to changes, but that's the reason why the direction is provided at that point.

Regarding unselection, its an interesting concept -- although I don't know that a user would need to unselect a study region; they could just click the one they are interested in?

Re the popup indicator results, open to contributions for how to make that clearer -- there is an "i" information icon next to the name that when clicked also opens the popup, once processed. If analysis hasn't been run, the following message appears if the information icon is clicked. Perhaps you could add more directions here if needed?

I'm open to changes to the compare screen - contributions welcome :)

Re comparing study regions, to me 'View comparison' means the same thing. Could change the text?

But --- I think you may have been using an older version of the software so some things may already be a bit different.

Hope the above clarifications are useful, and as above, if you would like to make contributions via a pull request to propose addressing anything, that is absolutely welcome. Thanks!

[jiyoon0120]

@carlhiggs
My apologies. I used the software that I downloaded in the summer, which was 4.5.2 with docker desktop 4.30.0.

I just downloaded the new version and ran it again. And yes, the second URL is gone now.

What I meant 'Change the name of the folder to ‘reports’ was changing the word on the instruction website.

Same with the 'View comparison', I suggested changing the word in the instruction to ‘VIEW COMPARISON’ and ‘EXPORT COMPARISON’ because I thought there was an icon 'View comparison'.

For the popup indicator results, maybe we can add 'more information' that people can click on?

Thanks!

[carlhiggs]

Thanks for picking up on these documentation aspects @jiyoon0120 --- Zara is currently updating our software instruction wiki and may be able to assist with some of these changes. @zarayousefi would you mind having a look at Jiyoon's suggestions for updates above and taking these into account when updating the Wiki? Thanks both!

[zarayousefi]

@carlhiggs @jiyoon0120
Hi both,
Yes sure.
This is what you mean Jiyoon? I changed web- report to report.

Do you mean to change "compare" to "VIEW COMPARISON" and "EXPORT COMPARISON"?

I am not sure if I get the pop-up indicator result. Where is that exactly?

Cheers,
Zahra

[jiyoon0120]

@zarayousefi
Thanks for working on it!
No, as you already revised the instruction for the Compare, it looks fine. No need to revise.

The pop-up indicator result shows up when you click the region area figure on the map in the software. I think we can discuss more on this about how to revise the design to be more intuitive.

Thanks,
Jiyoon

[jiyoon0120]

Hello all, I'm just making a note to clarify outstanding issues/suggestions to tackle

Outstanding suggestions for GHSCI v4.6.0

• Indicate the version of the software both in the instruction and the folder name of the software

• Clarifying the selection process by

• adding a small text 'click on a region from the list or on the map to select' under the "SELECT OR CREATE A NEW STUDY REGION"

and/or

• adding checkboxes next to each region listed at the bottom so it's clearer that they are selectable items.

• Clarifying the pop-up summary indication by

• Instead of having a codename as a tooltip when users hover over the study region on the map, display a tooltip saying "Click to view Study_region summary"

and

• When users hover over a region on the map, make them visually stand out with a border highlight in addition to the tooltip

and/or

• Instead of just the information icon, we can add a tooltip "View Region Summary" when users hover over the icon.

[carlhiggs]

Sounds good @jiyoon0120 , thanks for making the check boxes to keep us on track. If you're interested / it's helpful we could catch up sometime on teams/zoom and I could show you how I'd go about prototyping those changes (e.g. which file to edit, and how the nicegui framework that we are using works). You might be comfortable already with this kind of work, or interested in giving it a go, and if so you're most welcome to make some proposed edits and do a pull request. I'm in the UK for October so I think my 5pm will be your 9am. If you'd like to catch up some time later this week, we can if you'd like, to discuss how these changes could be made.

Otherwise, I'll see what I can do; a few competing priorities this month (and always; I only work one day/week on this project, and after meetings not so much time left). But we'll get there eventually!