ph-submissions Creating a Dashboard for Interactive Data Visualization with Dash in Python

Programming Historian in English has received a proposal for a lesson, 'Creating a Dashboard for Interactive Data Visualization with Dash in Python' by @hluling.

I have circulated this proposal for feedback within the English team. We have considered this proposal for:

Openness: we advocate for use of open source software, open programming languages and open datasets
Global access: we serve a readership working with different operating systems and varying computational resources
Multilingualism: we celebrate methodologies and tools that can be applied or adapted for use in multilingual research-contexts
Sustainability: we're committed to publishing learning resources that can remain useful beyond present-day graphical user interfaces and current software versions

We are pleased to have invited @hluling to develop this Proposal into a Submission to be developed under the guidance of @caiocmello as editor.

The Submission package should include:

Lesson text (written in Markdown)
- For guidance, we recommend Sarah Simpkin's lesson Getting Started with Markdown
Figures: images / plots / graphs (if using)
Data assets: codebooks, sample dataset (if using)

We ask @hluling to share their Submission package with our Publishing team by email, copying in @caiocmello .

We've agreed a submission date of April. We ask @hluling to contact us if they need to revise this deadline.

When the Submission package is received, our Publishing team will process the new lesson materials, and prepare a Preview of the initial draft. They will post a comment in this Issue to provide the locations of all key files, as well as a link to the Preview where contributors can read the lesson as the draft progresses.

If we have not received the Submission package by April, @caiocmello will attempt to contact @hluling. If we do not receive any update, this Issue will be closed.

Our dedicated Ombudspersons are Ian Milligan (English), Silvia Gutiérrez De la Torre (español), Hélène Huet (français), and Luis Ferla (português) Please feel free to contact them at any time if you have concerns that you would like addressed by an impartial observer. Contacting the ombudspersons will have no impact on the outcome of any peer review.

Mar 19 '24 15:03 hawc2

Hello @caiocmello and @hluling,

You can find the key files here:

You can review a preview of the lesson here:

http://programminghistorian.github.io/ph-submissions/en/drafts/originals/interactive-data-visualization-dashboard

I do have a question about two .py files in the assets. As far as I can understand,

app-rq2.py is a script to download the data for Research Question 2 (RQ2)
rq2-download.py is a script showing how the dashboard was set up for RQ2

How come these scripts are provided separately, rather than included as code blocks within the lesson? (I am slightly confused about how these scripts differ from the main code, which you've collated together under app.py.)

Thank you for clarifying!

Apr 17 '24 16:04 charlottejmc

Thank you for processing these files, @charlottejmc!

Hello Luling @hluling,

What's happening now?

Your lesson has been moved to the next phase of our workflow which is Phase 2: Initial Edit.

In this Phase, your editor Caio @caiocmello will read your lesson, and provide some initial feedback. Caio will post feedback and suggestions as a comment in this Issue, so that you can revise your draft in the following Phase 3: Revision 1.

%%{init: { 'logLevel': 'debug', 'theme': 'dark', 'themeVariables': {
              'cScale0': '#444444', 'cScaleLabel0': '#ffffff',
              'cScale1': '#882b4f', 'cScaleLabel1': '#ffffff',
              'cScale2': '#444444', 'cScaleLabel2': '#ffffff'
       } } }%%
timeline
Section Phase 1 <br> Submission
Who worked on this? : Publishing Assistant (@charlottejmc) 
All  Phase 1 tasks completed? : Yes
Section Phase 2 <br> Initial Edit
Who's working on this? : Editor (@caiocmello)  
Expected completion date? : May 17
Section Phase 3 <br> Revision 1
Who's responsible? : Author (@hluling) 
Expected timeframe? : ~30 days after feedback is received

Note: The Mermaid diagram above may not render on GitHub mobile. Please check in via desktop when you have a moment.

Apr 17 '24 18:04 anisa-hawes

Hello @caiocmello and @hluling,

You can find the key files here:

.md: /en/drafts/originals/interactive-data-visualization-dashboard.md

images: [none]

assets: /assets/interactive-data-visualization-dashboard

You can review a preview of the lesson here:

http://programminghistorian.github.io/ph-submissions/en/drafts/originals/interactive-data-visualization-dashboard

I do have a question about two .py files in the assets. As far as I can understand,

app-rq2.py is a script to download the data for Research Question 2 (RQ2)

rq2-download.py is a script showing how the dashboard was set up for RQ2

How come these scripts are provided separately, rather than included as code blocks within the lesson? (I am slightly confused about how these scripts differ from the main code, which you've collated together under app.py.)

Thank you for clarifying!

Thank you @charlottejmc. To clarify:

app-rq2.py is a script showing how the dashboard was set up for RQ2
rq2-download.py is a script to download the data for RQ2

The two RQs are based on two different data sources. app.py has the code for RQ1, the two other .py files are for RQ2. The main procedure and logic is demonstrated with RQ1, so I thought it might be repetitive to explain it again with RQ2. But I'd be happy to incorporate the RQ2 code into the lesson main text if that makes more sense.

The reason to separate app-rq2.py from rq2-download.py is that it takes some time to retrieve data using the Chronicling America API (RQ2), so it's not practical to incorporate the download procedure into the dashboard script.

Apr 17 '24 19:04 hluling

Thank you @hluling, that makes good sense to me now. Anisa and I did find this slightly confusing upon initial processing of the lesson, so this might indicate it will be confusing to readers as well. One solution would be to keep the code in a separate asset folder, but give clearer instructions to readers explaining this choice.

I will let @caiocmello share his view on this too!

Apr 18 '24 10:04 charlottejmc

Dear @hluling,

It has been such a pleasure reading your lesson. I've learnt a lot from it and I'm sure it will be of great contribution to the PH! So, thanks very much for this! I took note of some suggestions I could provide you at this stage before it goes to external review. I hope they are useful in improving the accessibility and usability of this material. Comments below indicate the paragraph, as annotated in the preview version.

[ ] Paragraph 5: Although it is okay and, actually, recommended to keep research questions simple for this tutorial, I would suggest a slight change in the text to make it more accurate. The fact that the U.S. television stations mention words such as Putin and Zelensky in the same frequency doesn’t mean, necessarily, 'balanced coverage of the event'. Therefore, I would suggest avoiding the word ‘balanced’ by simply adapting the research question to something like: ‘...concerns how the U.S. television stations have covered the war in Ukraine. One way to address…’ (or explaining what you mean by 'balanced').
[ ] Paragraph 21: It would be interesting to add a line here to state the parameters you chose. Eg.: ‘For the purpose of this lesson, keywords chosen are x,y, z. The geographic market is x…’.
Scripts are linked in the other way around:
[x] Paragraph 39: The link for the script (data acquisition) is wrong. It should be https://github.com/programminghistorian/ph-submissions/blob/gh-pages/assets/interactive-data-visualization-dashboard/rq2-download.py
[x] Paragraph 41: The link for the script (coding dashboard) is wrong. It should be https://github.com/programminghistorian/ph-submissions/blob/gh-pages/assets/interactive-data-visualization-dashboard/app-rq2.py
Other general suggestions:
[ ] I think the reader would benefit from seeing a spoiler of the final product at the beginning of the lesson. It could be a screenshot of the dashboard (or even the link for the live demo version you provided (https://ph-dash-demo.onrender.com/). It would have helped me to understand what my goal was if I had seen it before starting the lesson. (Let me know what you think about this).
[ ] It would have also been helpful to know more about (to have a general overview of) the dataset from the beginning. This could be a screenshot, a table or 'schema'. Something that explains what is in there and how it is structured.
Regarding RQ1 and RQ2:

It was great to see that you included more than one research question in the lesson. Also, you provide a different set-up of the dashboard, showing how readers can customise it in different ways. This is excellent. I have, however, some suggestions regarding the way the RQs are structured in the text:

[ ] You present the two RQs at the beginning of the lesson. But it makes me (as a reader) feel like you forgot the second RQ along the text. In paragraph 17, for example, you say: 'To address the research question...', and I was confused whether you were talking about RQ1 or RQ2. Therefore, I would suggest mentioning at the beginning of the lesson that you will provide an 'extra' RQ for those interested in learning by building and customising different dashboards. This way, RQ2 would be presented just at the end of the text and framed as 'extra' (non-essential) content of this lesson.
[ ] Considering this lesson is focused on data visualisation, would it be possible to provide the data for RQ2, instead of providing the code to download it? I appreciate the exercise of collecting the data, but in this case, I think it took me a very long time to download it, when I was primarily focused on visualising. Also, if kept in the lesson, I think the script for downloading data for RQ2 would have to be explained in detail in the lesson, as it is not simple.
[ ] It would also be great to see a spoiler of the dashboard for RQ2. This way the reader can choose whether it is worth it to look at the 'extra' content.

Final comment:

All my suggestions are based on the understanding that this is an advanced lesson, as it involves cloning repositories, creating virtual environments, navigating directories using the command line, reading API documentation, writing functions, etc. Therefore, I don't see the immediate need to detail the code much more.

These are my initial suggestions and I look forward to hearing back from you. I hope this is useful and feel free to get in touch if you have any questions.

May 08 '24 21:05 caiocmello

Thank you very much @caiocmello – just a short note to let you and @hluling know that I've just taken care of switching the two asset links at paragraphs 39 and 41.

May 09 '24 10:05 charlottejmc

Thank you @caiocmello for the insightful feedback! I'm working on the edits. @charlottejmc: Thanks for changing the links! Do I just upload the updated materials to my original repo? I also want to insert figures, and I'm looking at the instructions described here. Am I supposed to add the .png files to my original repo? I'll refer to the figures in the main text.

May 12 '24 00:05 hluling

Hello Luling @hluling,

If you'd like to slot in some figure images, please either upload them to your repository where we can download them or email to us as before. Charlotte and I will process these next week and put them in place for you!

Thank you, Anisa

May 12 '24 08:05 anisa-hawes

What's happening now?

Hello Luling @hluling. Your lesson has been moved to the next phase of our workflow which is Phase 3: Revision 1.

This Phase is an opportunity for you to revise your draft in response to @caiocmello's initial feedback.

I've sent you an invitation to join us as an Outside Collaborator here on GitHub. This gives you the Write access you'll need to edit your lesson directly.

We ask authors to work on their own files with direct commits: we prefer you don't fork our repo, or use the Pull Request system to edit in ph-submissions. You can make direct commits to your file here: /en/drafts/originals/interactive-data-visualization-dashboard.md. Charlotte and I can help if you encounter any practical problems!

When you and Caio are both happy with the revised draft, we will move forward to Phase 4: Open Peer Review.

%%{init: { 'logLevel': 'debug', 'theme': 'dark', 'themeVariables': {
              'cScale0': '#444444', 'cScaleLabel0': '#ffffff',
              'cScale1': '#882b4f', 'cScaleLabel1': '#ffffff',
              'cScale2': '#444444', 'cScaleLabel2': '#ffffff'
       } } }%%
timeline
Section Phase 2 <br> Initial Edit
Who worked on this? : Editor (@caiocmello) 
All  Phase 2 tasks completed? : Yes
Section Phase 3 <br> Revision 1
Who's working on this? : Author (@hluling)  
Expected completion date? : June 12
Section Phase 4 <br> Open Peer Review
Who's responsible? : Reviewers (TBC) 
Expected timeframe? : ~60 days after request is accepted

Note: The Mermaid diagram above may not render on GitHub mobile. Please check in via desktop when you have a moment.

May 12 '24 14:05 anisa-hawes

Hi @caiocmello, thanks again for the thorough review! Please see the revised lesson here: https://programminghistorian.github.io/ph-submissions/en/drafts/originals/interactive-data-visualization-dashboard Feel free to let me know if I need to change anything else. Here is the list responding to each of your comments.

[x] Paragraph 5: Although it is okay and, actually, recommended to keep research questions simple for this tutorial, I would suggest a slight change in the text to make it more accurate. The fact that the U.S. television stations mention words such as Putin and Zelensky in the same frequency doesn’t mean, necessarily, 'balanced coverage of the event'. Therefore, I would suggest avoiding the word ‘balanced’ by simply adapting the research question to something like: ‘...concerns how the U.S. television stations have covered the war in Ukraine. One way to address…’ (or explaining what you mean by 'balanced').

Revised as suggested (now in Paragraph 9).

[x] Paragraph 21: It would be interesting to add a line here to state the parameters you chose. Eg.: ‘For the purpose of this lesson, keywords chosen are x,y, z. The geographic market is x…’.

Revised as suggested (now in Paragraph 30).

[x] I think the reader would benefit from seeing a spoiler of the final product at the beginning of the lesson. It could be a screenshot of the dashboard (or even the link for the live demo version you provided (https://ph-dash-demo.onrender.com/). It would have helped me to understand what my goal was if I had seen it before starting the lesson. (Let me know what you think about this).

This is a great idea. I added Figure 1 and Figure 2 showing screenshots for the two dashboard.

[x] It would have also been helpful to know more about (to have a general overview of) the dataset from the beginning. This could be a screenshot, a table or 'schema'. Something that explains what is in there and how it is structured.

I agree. I added Figure 3 and Figure 4 showing screenshots for the two datasets.

[x] You present the two RQs at the beginning of the lesson. But it makes me (as a reader) feel like you forgot the second RQ along the text. In paragraph 17, for example, you say: 'To address the research question...', and I was confused whether you were talking about RQ1 or RQ2. Therefore, I would suggest mentioning at the beginning of the lesson that you will provide an 'extra' RQ for those interested in learning by building and customising different dashboards. This way, RQ2 would be presented just at the end of the text and framed as 'extra' (non-essential) content of this lesson.

I've revised and adjusted the language about the role of the two RQs (Paragraphs 4 and 27).

[x] Considering this lesson is focused on data visualisation, would it be possible to provide the data for RQ2, instead of providing the code to download it? I appreciate the exercise of collecting the data, but in this case, I think it took me a very long time to download it, when I was primarily focused on visualising. Also, if kept in the lesson, I think the script for downloading data for RQ2 would have to be explained in detail in the lesson, as it is not simple.

I've added a link to download the dataset directly (Paragraph 48).

[x] It would also be great to see a spoiler of the dashboard for RQ2. This way the reader can choose whether it is worth it to look at the 'extra' content.

The added Figure 2 shows a screenshot of the RQ2 dashboard.

May 13 '24 02:05 hluling

Hi Anisa @anisa-hawes (thanks for the reply!) and @charlottejmc,

I've placed the 4 figures here: https://github.com/hluling/ph-dash/tree/master/interactive-data-visualization-dashboard. You can find the figure placeholders in the revised lesson draft: https://programminghistorian.github.io/ph-submissions/en/drafts/originals/interactive-data-visualization-dashboard

Also a quick note: I updated some files here: https://github.com/programminghistorian/ph-submissions/tree/gh-pages/assets/interactive-data-visualization-dashboard

May 13 '24 02:05 hluling

Thank you @hluling, I've uploaded your four images and updated the placeholder links in the markdown file.

May 15 '24 08:05 charlottejmc

Hi @hluling,

It looks great! Thanks for the rapid response and for your engagement in the process! @anisa-hawes and @charlottejmc will process the lesson to the next stage of external peer-reviewing. I will write to you soon once reviewers are assigned.

Best wishes, Caio

May 16 '24 01:05 caiocmello

Hello Luling @hluling,

What's happening now?

Your lesson has been moved to the next phase of our workflow which is Phase 4: Open Peer Review. This Phase will be an opportunity for you to hear feedback from peers in the community.

Caio @caiocmello has invited two reviewers to read your lesson, test your code, and provide constructive feedback. In the spirit of openness, reviews will be posted as comments in this Issue (unless you specifically request a closed review).

After both reviews, Caio will summarise the suggestions to clarify your priorities in Phase 5: Revision 2.

%%{init: { 'logLevel': 'debug', 'theme': 'dark', 'themeVariables': {
              'cScale0': '#444444', 'cScaleLabel0': '#ffffff',
              'cScale1': '#882b4f', 'cScaleLabel1': '#ffffff',
              'cScale2': '#444444', 'cScaleLabel2': '#ffffff'
       } } }%%
timeline
Section Phase 3 <br> Revision 1
Who worked on this? : Author (@hluling)
All  Phase 3 tasks completed? : Yes
Section Phase 4 <br> Open Peer Review
Who's working on this? : Diego Alves + Johannes Breuer
Expected completion date? : 22 July
Section Phase 5 <br> Revision 2
Who's responsible? : Author (@hluling)
Expected timeframe? : ~30 days after editor's summary

Note: The Mermaid diagram above may not render on GitHub mobile. Please check in via desktop when you have a moment.

May 16 '24 09:05 anisa-hawes

Hello Luling @hluling,

I noticed that you updated the Open in Colab button link: https://github.com/programminghistorian/ph-submissions/commit/e5c835080751bf4ed00606328bd507349159f112 but this was correct as we had it set up: https://colab.research.google.com/github/programminghistorian/ph-submissions/blob/gh-pages/assets/interactive-data-visualization-dashboard/interactive-data-visualization-dashboard.ipynb. We are hosting your Python notebook within our organisational Colab space and syncing this copy with the assets folder on our repo. If you want to make any edits or adjustments to the notebook, please coordinate with us. Either we can make the changes on your behalf, or we can add you as a co-editor on our Master copy of your notebook. We are not making any direct edits to the notebook here in the repo, rather we update the Master copy on Colab, then re-sync.

Thank you, Anisa

May 19 '24 09:05 anisa-hawes

Thanks, @anisa-hawes. Sorry about that. I will let you know when there are changes.

May 19 '24 13:05 hluling

Hi @hluling,

I apologise for the confusion. When you updated the notebook in your Phase 3 Revision commit, we didn't realise that this had replaced the code behind the Open in Colab button. I do appreciate that you noticed and tried to rectify it later!

However, what we actually need is for the link to refer back to the notebook as hosted on our own GitHub repo: you can see that I've changed it back to link to: https://colab.research.google.com/github/programminghistorian/ph-submissions/blob/gh-pages/assets/interactive-data-visualization-dashboard/interactive-data-visualization-dashboard.ipynb, rather than: https://colab.research.google.com/github/hluling/ph-dash/blob/master/interactive-data-visualization-dashboard.ipynb (While you'd renamed the .ipynb file correctly here, the button was still linking back to your own GitHub repo.)

May 22 '24 08:05 charlottejmc

Open Peer Review

During Phases 2 and 3, I provided initial feedback on this lesson, then worked with @hluling to complete a first round of revisions.

In Phase 4 Open Peer Review, we invite feedback from others in our community.

Welcome Diego Alves @dfvalio and Johannes Breuer @jobreu. By participating in this peer review process, you are contributing to the creation of a useful and sustainable technical resource for the whole community. Thank you.

Please read the lesson, test the code, and post your review as a comment in this issue by July 22.

Reviewer Guidelines:

https://programminghistorian.org/en/reviewer-guidelines

A preview of the lesson:

http://programminghistorian.github.io/ph-submissions/en/drafts/originals/interactive-data-visualization-dashboard

-- Notes:

All participants in this discussion are advised to read and be guided by our shared Code of Conduct.
Members of the wider community may also choose to contribute reviews.
All participants must adhere to our anti-harassment policy:

Anti-Harassment Policy

This is a statement of the Programming Historian's principles and sets expectations for the tone and style of all correspondence between reviewers, authors, editors, and contributors to our public forums.

Programming Historian in English is dedicated to providing an open scholarly environment that offers community participants the freedom to thoroughly scrutinise ideas, to ask questions, make suggestions, or request clarification, but also provides a harassment-free space for all contributors to the project, regardless of gender, gender identity and expression, sexual orientation, disability, physical appearance, body size, race, age or religion, or technical experience. We do not tolerate harassment or ad hominem attacks of community participants in any form. Participants violating these rules may be expelled from the community at the discretion of the editorial board. If anyone witnesses or feels they have been the victim of the above described activity, please contact our ombudsperson Dr Ian Milligan. Thank you for helping us to create a safe space.

May 22 '24 18:05 caiocmello

Thanks a lot to @hluling for writing this tutorial and thanks to @caiocmello and @anisa-hawes for inviting and adding me, and giving me the opportunity to (p)review this tutorial!

First of all, I want to say that I enjoyed reading and testing this tutorial. It covers a very interesting and relevant topic and I find it very well-structured and helpful.

All of the suggestions that I have are rather minor and should be easy to address (I think/hope).

I will go through my comments in chronological order in the following:

Paragraph 1: I think, I would remove the following sentence: “It would be beneficial for scholars to explore ways to better engage with a broader audience.”
Paragraphs 2 and 4: Maybe it would be helpful for readers to explicitly distinguish (in the explanatory/introductory text) between a contemporary/current research question/topic (RQ1) and a historical one (RQ2)?
Paragraph 5: I found the text and numbers in the “Screenshot of the RQ2 dashboard” a bit hard to read (even in the enlarged version). Could the font size or zoom factor maybe be increased here?
Paragraph 6: In the last sentence, it may make sense to add that the created visualizations are interactive and that the deployment via a (free) web service makes the widely and easily accessible.
Paragraph 9: When mentioning content analysis and algorithmic text analysis for the first time, I would suggest adding links to some resources with (further) explanations. For content analysis, I guess, this could simply be the Wikipedia entry. To be honest, I have not heard the term “algorithmic text analysis” (ATA) before. A quick web search brought up this handbook entry. Terms that I (as a quantitative social scientist) am more familiar with, are text mining, text as data, and natural language processing (NLP). Maybe it could be worthwhile to briefly state how ATA relates to text mining and NLP? (Could be a short footnote, I think).
Paragraph 18: I think, the link to Flask should rather be this one.
Paragraph 20: There also is a GitHub CLI tool that could be added as an option for working with/via the command line in the 6th bullet point (as an alternative to GitHub desktop).
Paragraph 20: Maybe add a link to the Project Jupyter website when mentioning Jupyter Notebook for the 1st time in the “Optional” note at the end of this paragraph?
Paragraph 28: The link to the “the Jupyter Notebook version of the code here” did not work for me. It seems that the file name has changed.
I think it would be helpful to repeat the RQs in a shortened form in the (sub-)headings “RQ1” and “RQ2” at the respective beginnings of paragraphs 29 and 48. Suggestions: “RQ1 – TV airtime”, “RQ2 – Non-English newspapers” (or something similar). As a related sidenote: For the sake of consistency, I would suggest sticking with Arabic numerals and change the headings “Research Question I” (para. 9) and “Research Question II” (para. 14) to “Research Question 1” and “Research Question 2”.
Paragraph 33: The links to the Bootstrap resources did not work for me (server not found error).
Paragraph 39: Especially for the local use/testing, it would be helpful to add the code for stopping the app here as well, I would say.
Paragraphs 48 & 49: I fully understand that the author cannot provide “a detailed explanation considering the space limit” (para. 28). However, I think, it would be helpful to at least briefly sketch how the steps that the tutorial goes through for RQ1 could be repeated for RQ2 in 2 or 3 sentences (e.g., create new venv, run .py script + create GH repo and deploy with Blender or some other service, if readers want to test deployment as well for this).
Paragraphs 51 to 60 (Bibliography + Endnotes): I was a bit confused by the repetition of the references under the “Bibliography” heading and the endnotes. I am not sure whether this is standard practice at Programming Historian but would feel that removing the “Bibliography” section would be ok, given that the references are all provided in the endnotes.

As a a general remark: The tutorial text contains a few typos that warrant another thorough proofreading. I guess, this could be done using a tool like Grammarly, Writefull, Language Tool, or DeepL Write (by copying and pasting the text parts into the respective web or desktop apps). For example, there seem to be missing articles in the bullet points of paragraph 7: “… an Application Programming Interface (API)” and “… the dashboard…”

Going beyond the tutorial text, I also tested the Colab version of the Jupyter Notebook for RQ1 and ran the code and app locally and everything worked fine 😊 There is only one minor thing I noticed: When copying the app.py file from the GitHub repo and then running the app locally, the data displayed in the app was from 2023 and not from today up to 120 days ago. I fixed this by replacing the code for the queries in the app.py file with that from the interactive-data-visualization-dashboard.ipynb file. I also tested the deployment via Render and it worked nicely.

Jul 10 '24 15:07 jobreu

Thanks very much @jobreu for your enlightening and detailed review. This is very helpful and we appreciate that! I would like to ask the author @hluling to please wait until we receive feedback from the second reviewer @dfvalio, before you start editing or making changes to your lesson.

Jul 10 '24 16:07 caiocmello

Hi everyone, First of all, I would like to thank @hluling for preparing this tutorial. Overall, it is well-structured and easy to follow. However, as it involves many different platforms, it can be a bit complicated for beginners.

Please find my comments below:

Paragraph 1: The advantages of providing a dashboard could be further developed. For example, the author could explain what sort of advanced analysis can be done with a dashboard compared to a simple non-interactive graph.
Paragraph 2: It would be better to clarify that the two research questions are independent.
Paragraph 5: The figure shows a comparison of two graphs from different decades, but there is no information regarding the analysis. What do the percentages mean? This information should be added somewhere in the text.
Paragraph 9: After the sentence "The quantitative method of content analysis (CA) has long been a tradition in mass communication studies," it would be helpful to provide some examples (references) of studies using this method. Additionally, I agree with @jobreu that the term ATA might be unfamiliar. Consider using a more standard term or providing a better explanation.
Paragraphs 10 to 13: I recommend adding information about the specific data used for RQ1 in the dataset description. While this information appears later in the text, defining the keywords and timeframe in this part would be beneficial.
Paragraph 14: Clarify what type of change will be measured. Adding a sentence explaining the focus of RQ would enhance clarity.
Paragraph 17: Include more information about the timeframe used in the tutorial. Additionally, clarify what "percentage of newspaper" refers to. Percentage regarding what exactly?
Paragraph 21: If this lesson is aimed at people with some programming experience, the text is fine. For a less experienced audience, consider explaining (in a footnote) what a virtual environment is and why it is a good practice.
Paragraph 27: Since this part of the lesson focuses on RQ1, I would remove the sentence related to RQ2.
After paragraph 30 and before the code: Add a sentence or title explaining what will be done next, similar to previous sections. This applies to the two other code lines after paragraph 31 as well.
Code: Take a look at the retrieved dataframe df_ukr.head() When using a .py script, the line should be print(df_ukr.head()) for it to be displayed in the command prompt. Also, the comment (#) could be clarified: "Display the first 5 rows of the data collected regarding the Ukrainian keywords." Additionally, you can mention that people can use .shape to check the size of the dataset.
Paragraph 39: Remind less experienced users not to close the command prompt while using the dashboard on the web browser.
Paragraph 46: “Add Environment Variable” was not in Advanced Settings but before it.
Paragraphs 48/49 and 51/60: I agree with @jobreu's comments.

It is good that you provided the Jupyter notebook, it will certainly be useful for many users. I hope my comments will be a valid help to improve this lesson. Thanks again for inviting me as a reviewer.

I hope this helps in refining the tutorial further. Best regards,

Diego

Jul 16 '24 12:07 dfvalio

Thanks very much @dfvalio for providing such thorough feedback on this piece!

Dear @hluling,

I've organised reviewers' feedback on this comment, combining them and adding some 'notes' that I hope can be helpful (My notes are just suggestions, though. Feel free to respond as you wish). Please, let me know if you need help with anything and feel free to ask questions to reviewers if you think something needs further clarification.

Best wishes, Caio

[ ] Paragraph 1: I think, I would remove the following sentence: “It would be beneficial for scholars to explore ways to better engage with a broader audience.”
[ ] Paragraph 1: The advantages of providing a dashboard could be further developed. For example, the author could explain what sort of advanced analysis can be done with a dashboard compared to a simple non-interactive graph. Caio's note: After saying that it has become a popular method (line 4), you could perhaps mention that interactive dashboards allow users to explore, compare and interrogate data according to their particular interests.
[ ] Paragraphs 2 and 4: Maybe it would be helpful for readers to explicitly distinguish (in the explanatory/introductory text) between a contemporary/current research question/topic (RQ1) and a historical one (RQ2)?
[ ] Paragraph 2: It would be better to clarify that the two research questions are independent.
[ ] Paragraph 5: I found the text and numbers in the “Screenshot of the RQ2 dashboard” a bit hard to read (even in the enlarged version). Could the font size or zoom factor maybe be increased here?
[ ] Paragraph 5: The figure shows a comparison of two graphs from different decades, but there is no information regarding the analysis. What do the percentages mean? This information should be added somewhere in the text. Caio's note: You could extend the figures' legends to include that info. Eg. 'Screenshot of the RQ2 dashboard. The chart shows the percentage of ...'
[ ] Paragraph 6: In the last sentence, it may make sense to add that the created visualizations are interactive and that the deployment via a (free) web service makes them widely and easily accessible.
[ ] Paragraph 9: When mentioning content analysis and algorithmic text analysis for the first time, I would suggest adding links to some resources with (further) explanations. For content analysis, I guess, this could simply be the Wikipedia entry. To be honest, I have not heard the term “algorithmic text analysis” (ATA) before. A quick web search brought up this handbook entry. Terms that I (as a quantitative social scientist) am more familiar with, are text mining, text as data, and natural language processing (NLP). Maybe it could be worthwhile to briefly state how ATA relates to text mining and NLP? (Could be a short footnote, I think).
[ ] Paragraph 9: After the sentence "The quantitative method of content analysis (CA) has long been a tradition in mass communication studies," it would be helpful to provide some examples (references) of studies using this method. Additionally, I agree with @jobreu that the term ATA might be unfamiliar. Consider using a more standard term or providing a better explanation. Caio's note: Regarding the 'content analysis', I agree with Johannes that adding a reference for the Wikipedia entry would be sufficient. For ATA, there is consensus in reviewers' feedback that it needs a brief contextualisation. I also wonder how it differs from text mining. It can be a footnote, though!
[ ] Paragraphs 10 to 13: I recommend adding information about the specific data used for RQ1 in the dataset description. While this information appears later in the text, defining the keywords and timeframe in this part would be beneficial.
[ ] Paragraph 14: Clarify what type of change will be measured. Adding a sentence explaining the focus of RQ would enhance clarity. Caio's note: It seems like the dashboard for RQ2 just provides info on the ranking of languages with most newspapers published in the US. Therefore, you could slightly change RQ2 to something like: 'How has the ranking of top non-English languages of newspapers published in the United States changed dating back to the 1960s'. The ranking changed, not the languages, right?
[ ] Paragraph 17: Include more information about the timeframe used in the tutorial. Additionally, clarify what "percentage of newspaper" refers to. Percentage regarding what exactly?
[ ] Paragraph 18: I think, the link to Flask should rather be this one.
[ ] Paragraph 20: There also is a GitHub CLI tool that could be added as an option for working with/via the command line in the 6th bullet point (as an alternative to GitHub desktop).
[ ] Paragraph 20: Maybe add a link to the Project Jupyter website when mentioning Jupyter Notebook for the 1st time in the “Optional” note at the end of this paragraph?
[ ] Paragraph 21: If this lesson is aimed at people with some programming experience, the text is fine. For a less experienced audience, consider explaining (in a footnote) what a virtual environment is and why it is a good practice.
[ ] Paragraph 27: Since this part of the lesson focuses on RQ1, I would remove the sentence related to RQ2.
[ ] Paragraph 28: The link to the “the Jupyter Notebook version of the code here” did not work for me. It seems that the file name has changed.
[ ] Paragraphs 29 and 48: I think it would be helpful to repeat the RQs in a shortened form in the (sub-)headings “RQ1” and “RQ2” at the respective beginnings of paragraphs 29 and 48. Suggestions: “RQ1 – TV airtime”, “RQ2 – Non-English newspapers” (or something similar). As a related sidenote: For the sake of consistency, I would suggest sticking with Arabic numerals and change the headings “Research Question I” (para. 9) and “Research Question II” (para. 14) to “Research Question 1” and “Research Question 2”.
[ ] After paragraph 30 and before the code: Add a sentence or title explaining what will be done next, similar to previous sections. This applies to the two other code lines after paragraph 31 as well.
[ ] Paragraph 32: Code: Take a look at the retrieved dataframe df_ukr.head() When using a .py script, the line should be print(df_ukr.head()) for it to be displayed in the command prompt. Also, the comment (#) could be clarified: "Display the first 5 rows of the data collected regarding the Ukrainian keywords." Additionally, you can mention that people can use .shape to check the size of the dataset.
[ ] Paragraph 33: The links to the Bootstrap resources did not work for me (server not found error). Caio's note: It worked for me. That's weird
[ ] Paragraph 39: Especially for the local use/testing, it would be helpful to add the code for stopping the app here as well, I would say.
[ ] Paragraph 39: Remind less experienced users not to close the command prompt while using the dashboard on the web browser.
[ ] Paragraph 46: “Add Environment Variable” was not in Advanced Settings but before it.
[ ] Paragraphs 48 & 49: I fully understand that the author cannot provide “a detailed explanation considering the space limit” (para. 28). However, I think, it would be helpful to at least briefly sketch how the steps that the tutorial goes through for RQ1 could be repeated for RQ2 in 2 or 3 sentences (e.g., create new venv, run .py script + create GH repo and deploy with Blender or some other service, if readers want to test deployment as well for this).
[ ] Paragraphs 51 to 60 (Bibliography + Endnotes): I was a bit confused by the repetition of the references under the “Bibliography” heading and the endnotes. I am not sure whether this is standard practice at Programming Historian but would feel that removing the “Bibliography” section would be ok, given that the references are all provided in the endnotes. Caio's note: May I ask @anisa-hawes and @charlottejmc to clarify this last point on the bibliography?

Jul 16 '24 21:07 caiocmello

Many thanks for contributing as reviewers, Diego @dfvalio and Johannes @jobreu! We sincerely appreciate your generous participation.

And thank you @caiocmello for your thorough summary comment. I agree that it makes good sense to remove the bibliography in this case, as all works referenced are cited within the endnotes.

--

Hello Luling @hluling,

What's happening now?

Your lesson has been moved to the next phase of our workflow which is Phase 5: Revision 2.

This phase is an opportunity for you to revise your draft in response to the peer reviewers' feedback.

Caio @caiocmello has summarised their suggestions, but feel free to ask questions if you are unsure.

Please make revisions via direct commits to your file: /en/drafts/originals/interactive-data-visualization-dashboard.md. Charlotte and I are here to help if you encounter any difficulties.

When you and Editor are both happy with the revised draft, the Managing Editor @hawc2 will read it through before we move forward to Phase 6: Sustainability + Accessibility.

%%{init: { 'logLevel': 'debug', 'theme': 'dark', 'themeVariables': {
              'cScale0': '#444444', 'cScaleLabel0': '#ffffff',
              'cScale1': '#882b4f', 'cScaleLabel1': '#ffffff',
              'cScale2': '#444444', 'cScaleLabel2': '#ffffff'
       } } }%%
timeline
Section Phase 4 <br> Open Peer Review
Who worked on this? : Reviewers (@dfvalio+ @jobreu)
All  Phase 4 tasks completed? : Yes
Section Phase 5 <br> Revision 2
Who's working on this? : Author (@hluling)
Expected completion date? : August 18
Section Phase 6 <br> Sustainability + Accessibility
Who's responsible? : Publishing Team
Expected timeframe? : 7~21 days

Note: The Mermaid diagram above may not render on GitHub mobile. Please check in via desktop when you have a moment.

Jul 17 '24 13:07 anisa-hawes

Hi Charlotte @charlottejmc, I need to replace Figure 2 in the lesson. Could you please help me with this? Here is the new version: interactive-data-visualization-dashboard2

Thank you @dfvalio and @jobreu for the detailed feedback! Thanks @caiocmello for combining the comments! I've revised the lesson and will address each of the comment below. When a revision is described, the added or edited texts are in italics.

[x] Paragraph 1: I think, I would remove the following sentence: “It would be beneficial for scholars to explore ways to better engage with a broader audience.”

I've removed the sentence.

[x] Paragraph 1: The advantages of providing a dashboard could be further developed. For example, the author could explain what sort of advanced analysis can be done with a dashboard compared to a simple non-interactive graph. Caio's note: After saying that it has become a popular method (line 4), you could perhaps mention that interactive dashboards allow users to explore, compare and interrogate data according to their particular interests.

Added the following: "Unlike static graphs, interactive dashboards allow readers to explore patterns in the data based on their specific interests by filtering, sorting, or changing data view. Features like hover-over tooltips can also provide additional information without cluttering the main display."

[x] Paragraphs 2 and 4: Maybe it would be helpful for readers to explicitly distinguish (in the explanatory/introductory text) between a contemporary/current research question/topic (RQ1) and a historical one (RQ2)?

[x] Paragraph 2: It would be better to clarify that the two research questions are independent.

Please see the following edits. Paragraph 2: "... this lesson is guided by two independent sample research questions in the field of media and communication studies, each representing a different temporal focus. The first research question (RQ1) is contemporary and asks:" Paragraph 4: "To broaden the application settings of the current lesson, I also provide a historical example with the second research question (RQ2):"

[x] Paragraph 5: I found the text and numbers in the “Screenshot of the RQ2 dashboard” a bit hard to read (even in the enlarged version). Could the font size or zoom factor maybe be increased here?

[x] Paragraph 5: The figure shows a comparison of two graphs from different decades, but there is no information regarding the analysis. What do the percentages mean? This information should be added somewhere in the text. Caio's note: You could extend the figures' legends to include that info. Eg. 'Screenshot of the RQ2 dashboard. The chart shows the percentage of ...'

I have increased the chart size and the font size, as shown in the new Figure 2 (please see above). In the caption, I have also added the following description “Each chart shows the top-10 non-English newspapers in a given decade. The percentage is the count of newspaper titles in a given non-English language divided by the sum of non-English newspaper titles.”

[x] Paragraph 6: In the last sentence, it may make sense to add that the created visualizations are interactive and that the deployment via a (free) web service makes them widely and easily accessible.

The following changes are made: “The approach taken by this lesson can be applied to a wide range of digital humanities projects where there is a need to retrieve data from a publicly available source, process and analyze the data, and visualize the research outputs in an interactive manner. In addition, this lesson also shows how to deploy the RQ1 dashboard via a freemium web service, which helps to make similar dashboards widely and easily accessible.”

[x] Paragraph 9: When mentioning content analysis and algorithmic text analysis for the first time, I would suggest adding links to some resources with (further) explanations. For content analysis, I guess, this could simply be the Wikipedia entry. To be honest, I have not heard the term “algorithmic text analysis” (ATA) before. A quick web search brought up this handbook entry. Terms that I (as a quantitative social scientist) am more familiar with, are text mining, text as data, and natural language processing (NLP). Maybe it could be worthwhile to briefly state how ATA relates to text mining and NLP? (Could be a short footnote, I think).

[x] Paragraph 9: After the sentence "The quantitative method of content analysis (CA) has long been a tradition in mass communication studies," it would be helpful to provide some examples (references) of studies using this method. Additionally, I agree with @jobreu that the term ATA might be unfamiliar. Consider using a more standard term or providing a better explanation. Caio's note: Regarding the 'content analysis', I agree with Johannes that adding a reference for the Wikipedia entry would be sufficient. For ATA, there is consensus in reviewers' feedback that it needs a brief contextualisation. I also wonder how it differs from text mining. It can be a footnote, though!

ATA was used because it emphasized “algorithmic,” which I believe is a useful distinction from CA. I agree with including the more popular and general terms of text mining and NLP. In the revised paragraph, I’ve elaborated on (briefly) the difference between ATA and CA, included more references to CA and ATA, and referred to text mining and NLP when ATA is discussed:

“Both methods aim to infer meanings from text through classification or measurement. Whereas CA relies heavily on a carefully crafted codebook based on research questions and multiple human coders to ensure the reliability and validity of a systematic analysis,[2] [3] ATA relies on algorithms and models (a more general term for this method is text mining or natural language processing).[4]" In endnotes, here are the added references: [2]: Matthew Lombard, Jennifer Snyder‐Duch, and Cheryl Campanella Bracken. "Content Analysis in Mass Communication: Assessment and Reporting of Intercoder Reliability," Human Communication Research 28, no. 4 (2002): 587-604. [3]: Kimberly A. Neuendorf, The Content Analysis Guidebook (Thousand Oaks: Sage, 2017). [4]: Gross, Justin, and Dana Nestor. "Algorithmic Text Analysis: Toward More Careful Consideration of Qualitative Distinctions," in Oxford Handbook of Engaged Methodological Pluralism in Political Science, eds. Janet M. Box-Steffensmeier, Dino P. Christenson, and Valeria Sinclair-Chapman (Oxford Academic, 2023).”

[x] Paragraphs 10 to 13: I recommend adding information about the specific data used for RQ1 in the dataset description. While this information appears later in the text, defining the keywords and timeframe in this part would be beneficial.

I added the following text: “Our goal is to retrieve the relevant data for RQ1 via the 2.0 TV API. Regarding keyword, some appropriate Ukraine-related terms can include "Ukrainian" and "Zelenskyy," and the Russia-related terms can include "Russian" and "Putin." With the 2.0 TV API, we also specify the TV geographic market to be "National;" the output mode is the normalized percentage of airtime (the y-axis of the line graph that we will create later); and the time range covers the last 365 days, including today. After data retrieval, we will prepare a dataset like this for visualization.”

[x] Paragraph 14: Clarify what type of change will be measured. Adding a sentence explaining the focus of RQ would enhance clarity. Caio's note: It seems like the dashboard for RQ2 just provides info on the ranking of languages with most newspapers published in the US. Therefore, you could slightly change RQ2 to something like: 'How has the ranking of top non-English languages of newspapers published in the United States changed dating back to the 1960s'. The ranking changed, not the languages, right?

I made the following change to clarify: “How has the ranking of top non-English languages of American newspapers changed from the 1690s to the present? Specifically, the dashboard will be designed to show the top ten languages for each decade dating back to the 1690s, highlighting any shifts in their rankings and the emergence or decline of different languages over time.” Upon further check, I decided to use “American newspapers” in RQ2 to make it more precise to describe the pre-1776 period. The same change has been made in the Introduction. In the same paragraph, upon further check, I’ve also included a brief description on non-English Native American newspapers and the relevant references.

[x] Paragraph 17: Include more information about the timeframe used in the tutorial. Additionally, clarify what "percentage of newspaper" refers to. Percentage regarding what exactly?

I’ve revised the paragraph to improve clarity: “In Figure 4, the rows represent languages, the columns represent decades (from the 1690s to the 2020s), and the cells represent counts of newspaper. We can use the cell values to calculate the percentage for a given newspaper language in a certain decade. The percentage is calculated by dividing the number of newspapers for a given language in a certain decade by the total number of non-English newspapers in that decade, and then multiplying by 100. This gives the proportion of newspapers for that language relative to all non-English newspapers in the same decade. Then, we can visualize what the top 10 non-English newspapers are in a certain decade.”

[x] Paragraph 18: I think, the link to Flask should rather be this one.

I’ve changed the URL to https://flask.palletsprojects.com. Opening this link will redirect to the latest version.

[x] Paragraph 20: There also is a GitHub CLI tool that could be added as an option for working with/via the command line in the 6th bullet point (as an alternative to GitHub desktop).

[x] Paragraph 20: Maybe add a link to the Project Jupyter website when mentioning Jupyter Notebook for the 1st time in the “Optional” note at the end of this paragraph?

I’ve added this and Codespaces: “Have git ready to use in command line. You could also use either of the following (not covered in this lesson): * GitHub Desktop * GitHub CLI * GitHub Codespaces (costs may be incurred after you exceed the free quota)” Also, the link to the Project Jupyter website has been added.

[x] Paragraph 21: If this lesson is aimed at people with some programming experience, the text is fine. For a less experienced audience, consider explaining (in a footnote) what a virtual environment is and why it is a good practice.

I’ve added a footnote: “[11] A virtual environment in Python is a self-contained directory that contains a specific version of Python and a set of libraries. It allows you to manage dependencies for different projects separately, ensuring that changes in one project do not affect others. This is especially useful for maintaining consistent development environments and avoiding conflicts between package versions.”

[x] Paragraph 27: Since this part of the lesson focuses on RQ1, I would remove the sentence related to RQ2.

To improve clarity, I’ve removed the original section called “An Idea of a Simple Dashboard.” Its content related to RQ1 has been moved under “Coding the Dashboards -> RQ1,” and the content related to RQ2 has been moved under “Coding the Dashboards -> RQ2.”

[x] Paragraph 28: The link to the “the Jupyter Notebook version of the code here” did not work for me. It seems that the file name has changed.

I’ve updated the link.

[x] Paragraphs 29 and 48: I think it would be helpful to repeat the RQs in a shortened form in the (sub-)headings “RQ1” and “RQ2” at the respective beginnings of paragraphs 29 and 48. Suggestions: “RQ1 – TV airtime”, “RQ2 – Non-English newspapers” (or something similar). As a related sidenote: For the sake of consistency, I would suggest sticking with Arabic numerals and change the headings “Research Question I” (para. 9) and “Research Question II” (para. 14) to “Research Question 1” and “Research Question 2”.

The suggested changes have been made.

[x] After paragraph 30 and before the code: Add a sentence or title explaining what will be done next, similar to previous sections. This applies to the two other code lines after paragraph 31 as well.

[x] Paragraph 32: Code: Take a look at the retrieved dataframe df_ukr.head() When using a .py script, the line should be print(df_ukr.head()) for it to be displayed in the command prompt. Also, the comment (#) could be clarified: "Display the first 5 rows of the data collected regarding the Ukrainian keywords." Additionally, you can mention that people can use .shape to check the size of the dataset.

The paragraphs under question have been revised: “Next, once we have the data retrieved, we need to prepare the data in a way that is ready for visualization. Our goal is to transform the data into the shape shown in Figure 3, above.

def to_df(queryurl):
  response = requests.get(queryurl)
  content_text = StringIO(response.content.decode('utf-8'))
  df = pd.read_csv(content_text)
  return df

Code explanation: The requests library is used to execute the queries and transform the results into a pandas dataframe. To do this, we create a function called to_df() to streamline the workflow. Once we have the function created, we can now put it to work:

df_ukr = to_df(query_url_ukr)
df_rus = to_df(query_url_rus)

Optional: You can use the df.head() function to take a look at the first five rows of the output dataframe from the above action.

# If in Jupyter: Take a look at the first five rows of the retrieved dataframe for Ukraine 
df_ukr.head()
# If you execute a .py file, add the print() function to see the first five rows
print(df_ukr.head())
# You can also use the shape() function to see how many columns and rows there are in the dataframe. Give it a try!

”

[x] Paragraph 33: The links to the Bootstrap resources did not work for me (server not found error). Caio's note: It worked for me. That's weird

I’m able to open the links. Maybe their site was down when you tested it?

[x] Paragraph 39: Especially for the local use/testing, it would be helpful to add the code for stopping the app here as well, I would say.

[x] Paragraph 39: Remind less experienced users not to close the command prompt while using the dashboard on the web browser.

I’ve added the following: “Do not close the command line program when the server is running. When you are done, in command line, press ctrl+c on keyboard to stop the server.”

[x] Paragraph 46: “Add Environment Variable” was not in Advanced Settings but before it.

I’ve made the revision: “Second, scroll down and find the section called "Environment Variables."”

[x] Paragraphs 48 & 49: I fully understand that the author cannot provide “a detailed explanation considering the space limit” (para. 28). However, I think, it would be helpful to at least briefly sketch how the steps that the tutorial goes through for RQ1 could be repeated for RQ2 in 2 or 3 sentences (e.g., create new venv, run .py script + create GH repo and deploy with Blender or some other service, if readers want to test deployment as well for this).

I’ve added the following sentences for RQ2: “Regarding workflow, the following steps will be the same as described above: the same prerequisites will be needed; follow the same steps to create a new virtual environment; the same Python libraries will be needed; and you can follow the same steps to deploy the RQ2 dashboard on Render. The data downloading procedure and the specific code used for the RQ2 dashboard will be different from RQ1. However, the underlying logic is the same: We start with data retrieval, prepare the data for visualization, code the dashboard frontend, then code the dashboard backend. I will briefly describe these in the next two sections.”

[x] Paragraphs 51 to 60 (Bibliography + Endnotes): I was a bit confused by the repetition of the references under the “Bibliography” heading and the endnotes. I am not sure whether this is standard practice at Programming Historian but would feel that removing the “Bibliography” section would be ok, given that the references are all provided in the endnotes. Caio's note: May I ask @anisa-hawes and @charlottejmc to clarify this last point on the bibliography?

Per Anisa’s reply, I deleted the bibliography.

I hope that I have addressed the comments successfully. Thank you all again!

Aug 14 '24 02:08 hluling

Hi @hluling,

Just to let you know I've replaced Figure 2 with the new version! Thanks so much for all your energy with this.

Aug 29 '24 04:08 charlottejmc

Dear @caiocmello,

Once you've had a look through @hluling's Phase 5 Revisions and have confirmed you're happy with how the lesson now reads, please do let us know! We can then move to the next phase of the workflow, which is Phase 6: Sustainability & Accessibility. I'll begin with copyediting, before typesetting and the final checks.

Thank you! ✨

Aug 29 '24 05:08 charlottejmc

Hella @hawc2, if @caiocmello is indeed happy with the lesson at this stage, then it is ready for your final read-through before we move it to Phase 6. Thank you!

Sep 05 '24 01:09 charlottejmc

Dear @charlottejmc, I have revised this draft and I am happy for it to move on to Phase 6. Thanks very much @hluling for your work on this piece and for your careful editions, following the recommendations of reviewers.

Sep 06 '24 16:09 caiocmello

Thank you, @caiocmello.

Hello Luling @hluling,

The Managing Editor Alex @hawc2 will also read the lesson to confirm if it should be moved onwards to Phase 6, or if he'd like to suggest some further revisions.

Thank you, Anisa

Sep 06 '24 16:09 anisa-hawes

Hi @hluling, my apologies for delays getting back to you with my review - the start of the semester swept things away.

This is looking really interesting, but there are some sections of the code that seem to be too briefly described. There’s a few changes I’d recommend making to the framing and presentation of key details. I’ve made a round of line-edits where you can see some of the simple changes I made to the table of contents, headings, and the wording of some sections.

Right now the intro section focuses on showing the final dashboard images the lesson will produce. But this information would be better to save for the end of the lesson. Instead, spend more time in the intro discussing the datasets and general types of data visualizations you will produce. It’s not clear in the intro what kind of graph will be viewable in the end, and it’s not concrete what the publicly available data sources are that you selected to answer your research questions. You end up going into detail about that below, but you might as well say concretely what they are the first time you mention them.

This is a difficult lesson that requires some base knowledge of Python and deploying code, and it may be helpful to add some more prerequisite lessons and helpful references/guidelines for some of those complicated steps (like running Python in the command line when you first mention it).

All the sections that begin “Code explanation” shouldn’t include that phrase, they should just actually describe the code. These sections could all afford to include more commentary about the code. Ideally you have commentary before and after the code, so instead of just citing code and then providing one paragraph describing the code, weave the commentary before and after the code. Ideally code chunks are less long, and there’s more detail per each chunk of code. You do say that for Q2 you don't provide commentary because it's similar to Q1, but you should still provide some commentary to direct the reader.

Please take a look at most of our published lessons, and you will get a better idea of the custom for citing and discussing code.

Once you've made those revisions, I can take a final look over it for any other lingering questions relating to the overall structure and last section. Some of the formatting and related presentation of information will continue to get revised after we send this on for copyedits and for the publishing manager to review. Please let me know if you have questions!

Sep 18 '24 21:09 hawc2