Creating a Dashboard for Interactive Data Visualization with Dash in Python

[hawc2]

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.

[charlottejmc]

Hello @caiocmello and @hluling,

You can find the key files here:

• .md: /en/drafts/originals/interactive-data-visualization-dashboard.md
• images: images/interactive-data-visualization-dashboard
• 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!

[anisa-hawes]

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

Loading

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

[hluling]

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.

[charlottejmc]

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!

[caiocmello]

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:

• 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

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

[charlottejmc]

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.

[hluling]

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.

[anisa-hawes]

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

[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

Loading

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

[hluling]

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.

• 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).

• 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).

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

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

• 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).

• 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).

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

[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

[charlottejmc]

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

[caiocmello]

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

[anisa-hawes]

Thank you for your email, Luling @hluling. To confirm, we're looking forwards to receiving your revisions in early November. I've adjusted the timeframes above. Please don't hesitate to write to us if you have questions in the meantime 🙂

[hluling]

Hi Alex @hawc2, thanks again for the comments and edits. I've revised the lesson based on your feedback. Here is a summary of the revisions:

1. All languages about "RQ1" and "RQ2" have been removed. The main section is now called a case study. The second dashboard is now called an extended case.
2. In the introduction, I've added a screenshot showing the kind of dashboard that can be created using Dash (now Figure 1). For the TV airtime dashboard, I've added a screenshot of the date-range picker (now Figure 3).
3. I've added the explanation about why some of the Python libraries are needed. This is now under the section called "Import Libraries."
4. I've broken down those two long blocks of code and provided much more detailed explanation for each of the smaller pieces following the suggested format. See para. 57-68, and para. 72-80.
5. Wikipedia links for pandas and requests have been added (after para. 29)
6. There is a Colab button at the top of the provided Jupyter Notebook. Now this is explicitly mentioned in the lesson (para. 31).
7. The conclusion has been expanded, including a summary of lesson goals and takeaways (para. 124-133).
8. In the paragraph following the section called "Prepare for the lesson," I've included the instruction on how to run a python file in command line (para. 21).

I hope that I have addressed the comments successfully. Please let me know if any further revision is needed.

[anisa-hawes]

Thank you, Luling @hluling. We appreciate your work on these revisions.

--

Hello Alex @hawc2,

Please let us know when you've had time to review these revisions.
When you and @caiocmello both feel satisfied with the lesson, Charlotte & I will be pleased to support the next Phase 6.

[hawc2]

@hluling thank you for these thorough revisions, the lesson is much improved. It's an excellent exploration of building dashboards. @caiocmello could you look this over one last time and share any thoughts for revision before we send this to copyedits?

My only immediate thought for revision is mostly something we can address in copyedits: some of the section headings aren't very explanatory of what that section is like, such as down in the Extended Use Case area where there's a heading that's just Dataset.

I still plan to test the Colab notebook, make sure the code works still as expected, and come back separately if there are any changes I'd recommend for it. We can finalize the notebook after copyedits.

[caiocmello]

Thanks @hawc2 for your comments and @hluling for your excellent revisions on the document. I think the way you managed to present RQ2 now looks much better and easier to follow. I've read the lesson through again and I think it reads well! I don't have anything to add at this point.

[anisa-hawes]

Hello Luling @hluling,

What's happening now?

Your lesson has been moved to the next phase of our workflow which is Phase 6: Sustainability + Accessibility.

In this phase, our publishing team will coordinate a series of tasks including: copyediting, typesetting, generating archival links, collating copyright agreements, and reviewing essential metadata.

Please note that you won't have direct access to make further edits to your files during Phase 6. You will have an opportunity review and discuss suggested copyedits with your editor @caiocmello. Thank you for your understanding.

When our Sustainability + Accessibility actions are complete, the Managing Editor @hawc2 will read the lesson through one final time ahead of publication.

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

Loading

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

[charlottejmc]

Hello @hluling,

This lesson is now with me for copyediting. I aim to complete the work by ~21 November.

Please note that you won't have direct access to make further edits to your files during this phase.

Any further revisions can be discussed with your editor @caiocmello after copyedits are complete.

Thank you for your understanding.

[charlottejmc]

Hello @hluling and @caiocmello, I've prepared a PR with the copyedits for your review.

There, you'll be able to review the 'rich-diff' to see my edits in detail. You'll also find brief instructions for how to reply to any questions or comments which came up during the copyedit.

When you're both happy, we can merge in the PR.

[charlottejmc]

Hello @hawc2,

This lesson's sustainability + accessibility checks are in progress.

• Preview:

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

Publisher's sustainability + accessibility actions:

• Copyediting
• Typesetting
• Addition of Perma.cc links
• Check/resize images
• Check/adjust image filenames
• Receipt of author(s) copyright agreement – Hello @hluling, our authorial copyright declaration form is an opportunity to acknowledge copyright and grant us permission to publish the lesson. Could you download this, complete the details, and email it to me (publishing.assistant [@] programminghistorian.org)? Many thanks.
• Request DOI
• Remove outside contributors from ph-submissions

Authorial / editorial input to YAML:

• Define difficulty:, based on the criteria set out here
• Define the research activity: this lesson supports (acquiring, transforming, analysing, presenting, or sustaining) Choose one
• Define the lesson's topics: (api, python, data-management, data-manipulation, distant-reading, get-ready, lod ["Linked Open Data"], mapping, network-analysis, web-scraping, website ["Digital Publishing"], r, machine-learning, creative-coding, web-archiving or data-visualization) Choose one or more. Let us know if you'd like us to add a new topic. Topics are defined in /_data/topics.yml.
• Provide alt-text for all figures
• Provide a short abstract: for the lesson (1-2 sentences)
• Agree an avatar (thumbnail image) to accompany the lesson

The image must be:

• copyright-free
• non-offensive
• an illustration (not a photograph)
• at least 200 pixels width and height
• Image collections of the British Library, Internet Archive Book Images, Library of Congress Maps as well as their Photos/Prints/Drawings or the Virtual Manuscript Library of
  Switzerland are useful places to search

• Provide avatar_alt: (visual description of that thumbnail image)
• Provide author(s) bio for ph_authors.yml using this template:

- name: Forename Surname
  orcid: 0000-0000-0000-0000
  team: false
  bio:
    en: |
      Forename Surname is an Assistant Professor in the Department of Subject at the University of City.

Files we are preparing for transfer to Jekyll:

• .md file: /en/drafts/originals/interactive-data-visualization-dashboard.md
• images: /images/interactive-data-visualization-dashboard
• assets: /assets/interactive-data-visualization-dashboard
• original avatar: /gallery/originals/interactive-data-visualization-dashboard-original
• gallery avatar: /gallery/interactive-data-visualization-dashboard

Promotion:

• Prepare announcement post (using template)
• Prepare evergreen posts – @hawc2, could you please provide x2 posts for future promotion via our social media channels? You can add these directly to the ph-evergreens-blueksy spreadsheet that has been shared with you, or email them to me at publishing.assistant[@]programminghistorian.org.

Publisher's post-publication tasks:

• Add lesson slug to the Annual Count of Published Lessons
• Update the ph_data folder in the ph-contributors repository

[charlottejmc]

Hi @hluling,

What do you think about this thumbnail for your lesson? I think it represents the title 'interactive data visualization' rather well!

I also found this chart which could work, although it's not as playful as the first option.

Feel free to suggest your own images too (following the guidance above).

[hluling]

Thanks @charlottejmc, the first one looks great and let's use it! I also just emailed you the copyright agreement.

[charlottejmc]

Hi @hluling, we are very close to being able to publish your lesson. The final thing we need is your author bio, written in the following format:

• name: Forename Surname
  orcid: 0000-0000-0000-0000
  team: false
  bio:
  en: |
  Forename Surname is an Assistant Professor in the Department of Subject at the University of City.

Thank you very much for all your work and energy so far!

[anisa-hawes]

Hello Luling @hluling,

What's happening now?

Your lesson has been moved to the final phase of our workflow which is Phase 7: Publication.

In this phase, the Managing Editor @hawc2 will read your lesson through one more time, to provide final feedback or suggest additional revisions.

When you, your Editor @caiocmello and the Managing Editor @hawc2 all agree that the lesson is ready, I will stage it for publication.

%%{init: { 'logLevel': 'debug', 'theme': 'dark', 'themeVariables': {
              'cScale0': '#444444', 'cScaleLabel0': '#ffffff',
              'cScale1': '#882b4f', 'cScaleLabel1': '#ffffff',
              'cScale2': '#444444', 'cScaleLabel2': '#ffffff'
       } } }%%
timeline
Section Phase 6 <br> Sustainability + Accessibility
Who worked on this? : Publishing Team
All  Phase 6 tasks completed? : Author bio needed
Section Phase 7 <br> Publication
Who's working on this? : Managing Editor @hawc2
Expected timeframe? : ~10 days

Loading

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

[hluling]

Thanks @charlottejmc! Here is the author bio:

name: Luling Huang
orcid: 0000-0003-0139-1771
team: false
bio:
en: |
Luling Huang is an Assistant Professor in the Department of Communication at Missouri Western State University.

[hawc2]

@charlottejmc the copy edits look great, I see a few small line edits I would like to make, but before I do that, I think we might want to change the TOC in a couple places and reorder a section or two to make this lesson a little more streamlined. @anisa-hawes I'm thinking we should give this another week or so or time to further revision, and aim to publish by mid-late December.

• The Preparatory Steps section is so short, it seems odd to have it be standalone. I think we could move this down to the Coding the Dashboard section, as a way for it to start off with a more general introduction.

• The Coding the Dashboard section I believe should be renamed - it's a very long section, and Coding can mean multiple things. Maybe a more colloquial word, like Building the Dashboard, would be better for the title of this section. The word Coding gets used alot in the section headings and throughout the lesson as it is.

• I am also inclined to say that the Deploying the Dashboard section should be it's own main section, not a subsection of Building the Dashboard. This at least makes sense to me for the main body of the lesson. The second case study could be kept all one section, seeing how it's briefer and extending the first, main lesson section.

@hluling This draft has gone through some reordering and revision, and I'm worried there may be one or two explainers that now need to be clarified earlier or connected between sections. Would you like to also re-read it to double check?

• As one example, in the Preparatory Steps section, you give a very brief overview of how the user will run the Python file in the end to deploy the dashboard. Shortly thereafter, you overview the steps to Creating a Virtual Environment. It's unclear to me if this is an essential step of running the Python script each time or not. Do you think there's a brief addition we could make to clarify this connection?

• I should note generally that I'm leaning towards labeling this an Advanced lesson in terms of Difficulty. While it does Introduce concepts, the code and the level of complexity that it assumes the reader understands about code, makes it seem to me like it requires a lot of prerequisit knowledge and familiarity with Python and programming.

• As one example, the section Coding the Backend begins in this way: "Coding the Backendcoding-the-backend
  In the backend, the core concepts are the ‘callback decorator’ and the ‘callback function’." The lesson never really explains what a "decorator" is in the first place, maybe it's not essential knowledge to do this lesson, but insofar as it assumes that, it's more difficult. One further idea to make this a little more user-friendly would be to add additional links to relevant secondary resources like Wikipedia. That's not really desirable at this stage post-copyediting, but if you identify specific places you'd like to add references @hluling at this point, please let us know and we can slot them in.

It's generally best at this point that we keep further line edits to the Markdown file to a minimum, so make sure to use pull requests if you do any further edits to the file @hluling

[charlottejmc]

Hi @hawc2,

Thank you for your detailed read-through!

• I realised there was a mistake in the TOC here: ## Prerequisites was supposed to be a subheading under ## Preparatory steps: i.e. ### Prerequisites (then ### Creating a Virtual Environment and ### Installing Libraries). I've made that edit now. Does that look good to you?
• I've renamed the section to ## Building the Dashboard, and made ## Deploying the Dashboard its own section.
• The Difficulty level is set to 3 (advanced).

[hluling]

Thanks @hawc2 for the feedback and @charlottejmc for the edits! @charlottejmc's edits look good to me.

I've read it again, and I suggest the following edits:

As one example, in the Preparatory Steps section, you give a very brief overview of how the user will run the Python file in the end to deploy the dashboard. Shortly thereafter, you overview the steps to Creating a Virtual Environment. It's unclear to me if this is an essential step of running the Python script each time or not. Do you think there's a brief addition we could make to clarify this connection?

To address this, In para. 28, add this after the first sentence: "You should run a Python script in the command line when the virtual environment is activated."

As one example, the section Coding the Backend begins in this way: "Coding the Backendcoding-the-backend
In the backend, the core concepts are the ‘callback decorator’ and the ‘callback function’." The lesson never really explains what a "decorator" is in the first place, maybe it's not essential knowledge to do this lesson, but insofar as it assumes that, it's more difficult. One further idea to make this a little more user-friendly would be to add additional links to relevant secondary resources like Wikipedia. That's not really desirable at this stage post-copyediting, but if you identify specific places you'd like to add references @hluling at this point, please let us know and we can slot them in.

To address this, in para. 69, add hyperlinks like so (the same link explains both): 'callback decorator' & 'callback function'

Please let me know your thoughts and if there are any other areas that need changes.

[anisa-hawes]

Happy New Year, Luling @hluling! Thank you for sharing your thoughts in response to @hawc2's suggestions.

Alex will add a comment in the coming days to confirm whether he agrees with these edits and, if so, @charlottejmc can implement the changes on your behalf.

After that, we will be able to move forward to prepare for publication ☺️

[hawc2]

Thanks @hluling, these changes look good. My main concern with certain phrases is that they might not be totally explicit about the order of operations. For example, I'd recommend rephrasing the sentence so it reads more like: "Once the virtual environment has been activated, you can run the Python script in the command line." This makes it much clearer which step comes first.

@anisa-hawes is going to be doing one last read-through for clarity around the order of operations, and once we're done with those edits, we can move this forward for publication!

[anisa-hawes]

Hello @hawc2 and @hluling,

Thank you for the opportunity to read this lesson. @charlottejmc and I have collaborated to review the text again, and have made some further copyedits for clarity which you can review in rich-diff and check you're happy with: 52a0d34 and fa22abc.

A few further notes and observations I'd like to share:

Difficulty:

• Overall, I observe that there are a couple of odd shifts in how this lesson writes for its audience's learning level. This lesson is currently marked as difficulty level 3 (advanced) yet, in places, it covers detail that someone already proficient in Python wouldn’t need explaining (for example, basic command line instructions). In fact, in the Prerequisites section you do state that instructions for using GitHub in the command line will not be covered in your lesson.

Figures:

• As part of our commitment to accessibility we are phasing out screenshots of tabular data, so we have taken the initiative to replace Figures 2 & 5 with tables of raw sample data: 469f31e
• My view is that Figure 3 could be much more useful if it was a .gif rather than a .png, as it seems to primarily be provided to demonstrate an interactive feature. If you agree, perhaps you could create a GIF and share it with Charlotte by email?

Case Study:

• In this section, you introduce your approach describing it as "somewhere in between CA and ATA". As a reader, this paragraph doesn't explain to me why this in-between approach is beneficial. Can you clarify?

Why Dash in Python?

• In this section, we have adjusted things a little to bring in Grace Di Méo's recent lesson Creating Interactive Visualizations with Plotly. Again, as a reader I don't feel I have a clear understanding of how a researcher would choose which of these tools/which of these lessons is best for their use-case.

Prerequisites:

• I was a little surprised to read "A web browser" as one of the prerequisites here. The lesson abstract specifies that this lesson is about creating interactive web-based dashboards so I think the "browser" as one of the "things needed" is perhaps unnecessary?

Retrieving Data Using an API:

• A point of confusion for me when I read the line at the beginning of the following section Preparing Data for Visualization: "Once you have retrieved this data". I wasn't 100% clear that the commands in the section above (Retrieving Data Using an API) had actually done the retrieving. We've adjusted two sentences to clarify: "First, let's define a range of dates from which the API will retrieve data for our dataset" to "We are going to use an API query to retrieve data. First, let's define a date range [...]" and also edited this line very slightly: "Next, let's create two string objects which we'll use for our queries:" to "Next, let's create two string objects which we'll use for our retrieval queries:"

Coding the Backend:

• I was a little confused by what appears to be quite a simple instruction in this section which reads: " %b represents the shorthand name of the month (e.g. Dec for Decemeber); %d is the day and month (e.g. 01-31);" We suspect this is an error and should read: the day of the month.

Setting up in GitHub:

• I am not an advanced technician, but I found the original opening sentence You will need to upload the ph-dash folder to GitHub, as a repository unclear. Are we correct in understanding that this means that the ph-dash folder will become its own repository? If so, we have suggested You will need to turn the ph-dash folder into a GitHub repository, Again, I'm unsure about the lesson's difficulty level (I have not tested the steps of the lesson myself), but with things as they are at the moment, you might want to include the command line instruction git init which makes a folder into a repository.

Further Practice: Second Example:

• I note that there has been some discussion above about how the second case study fits into the lesson, but I did want to say that as a reader, I was surprised with how the section: ### Building the Dashboard begins and then swiftly ends with the line "This is the script for coding the dashboard". Of course, I leave it to @hawc2 to review and consider this and assess whether anything additional is needed. I understand that your advice is that the first case study should be the focus of the lesson, while the second one serves as an 'extension', showcasing in less detail what else is possible with the tools.

Some actions I'd like to suggest:

• @hluling: What do you think about creating Figure 3 as a GIF? If you like this idea, please share with Charlotte by email (publishing.assistant[@]programminghistorian.org).
• @hluling: In the Case Study section, could you add a few sentences to explain why this approach (described as in between CA and ATA) is beneficial?
• @hluling: In the Why Dash in Python? section, could you clarify how a researcher would choose between Dash and Plotly? (Which considerations are important when deciding which tool is best for their use-case?)

Thank you,
Anisa