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_Palmas2023.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.