Lesson Proposal: Creating Interactive Visualizations with Plotly

scottkleinman commented 2 years ago

The Programming Historian has received the following proposal for a lesson on 'Creating Interactive Visualizations with Plotly' by @gdmeo. The proposed learning outcomes of the lesson are:

Learning the distinction between Plotly Express, Plotly’s graph objects and Plotly Dash.
Learning how to create graphs using plotly.express and plotly.graph_objects
Learning how to add custom features to graphs
Learning methods for viewing and exporting graphs

The draft has been uploaded to https://github.com/programminghistorian/ph-submissions/blob/gh-pages/en/drafts/originals/interactive-visualization-with-plotly.md and staged at https://programminghistorian.github.io/ph-submissions/en/drafts/originals/interactive-visualization-with-plotly.

Note that figures in the draft have been removed because they contain dynamic code that will not render on GitHub. Each figure has been converted (for the moment) to a standalone web page and can be found in https://github.com/programminghistorian/ph-submissions/tree/gh-pages/assets/interactive-visualization-with-plotly. To view the figure, click on the link in the staged version of the tutorial. Eventually, we will try to embed the figures within the tutorial text itself if Jekyll allows.

I will act as editor for the review process. My role is to solicit two reviews from the community and to manage the discussions, which should be held here on this forum. I have already read through the lesson and provided feedback, to which the author has responded.

Members of the wider community are also invited to offer constructive feedback which should post to this message thread, but they are asked to first read our Reviewer Guidelines (reviewer guidelines) and to adhere to our anti-harassment policy (below). We ask that all reviews stop after the second formal review has been submitted so that the author can focus on any revisions. I will make an announcement on this thread when that has occurred.

I will endeavor to keep the conversation open here on Github. If anyone feels the need to discuss anything privately, you are welcome to email me. You can always turn to our ombudsperson (Dr Ian Milligan - i2milligan@uwaterloo.ca) if you feel there's a need for an ombudsperson to step in.

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.

The Programming Historian is dedicated to providing an open scholarly environment that offers community participants the freedom to thoroughly scrutinize ideas, to ask questions, make suggestions, or to requests for 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 - i2milligan@uwaterloo.ca). Thank you for helping us to create a safe space.

hawc2 commented 11 months ago

@gdmeo Thanks for turning to this so quickly despite the obstacles! It sounds easiest to cut down this section as you say. Can you take a shot at cutting it down and @scottkleinman can take a look to approve the new version as fitting with the flow of the lesson? I'd say lean towards cutting the least amount necessary, and then have @scottkleinman look to see whether that is sufficient.

gdmeo commented 11 months ago

@gdmeo Thanks for turning to this so quickly despite the obstacles! It sounds easiest to cut down this section as you say. Can you take a shot at cutting it down and @scottkleinman can take a look to approve the new version as fitting with the flow of the lesson? I'd say lean towards cutting the least amount necessary, and then have @scottkleinman look to see whether that is sufficient.

@hawc2 Yes, I think the easiest solution in this case to cut the example. As a first preference, I'll try to cut down the section on dropdown bars by removing only the first example (switching from bar chart to pie chart) but keeping the second example (toggling between scatter plots). For this I'll need to carry across some of the important concepts that were in example 1 and add them to example 2, but I don't think this will be too much of a rework. Failing that, or if Scott doesn't feel the flow works with these changes, I'll remove the section on dropdown bars entirely :)

I'll have a go at cutting and combining the section at some point over the next few days with my pad, but please bear in mind that I won't be able to error check as I don't have access to coding platforms! Is it best for me to add the changes to the code directly or to attached an amended MD file here/via email?

scottkleinman commented 11 months ago

Sadly, I agree with @gdmeo's assessment. Plotly Express just doesn't have a non-hacky way to switch between graph types. I'm going to suggest that the first example simply be removed from the tutorial. However, that section has some valuable discussion, so I think it needs to be retained in some way. I've pasted below one possible revision to the entire Dropdown Bars section. @gdmeo, if you are happy with this, I can make the appropriate changes.

Adding Animations: Dropdown Bars

Dropdown bars are slightly more complicated than animation frames. They can allow users to switch between a wide variety of display options, including changing colours, lines, axes and even variables. When creating figures with dropdown bars, the first step is to create the initial graph without a dropdown bar (this will be the first graph which your users will see).

fig = px.scatter(
    phl_crime,
    x="Age of accused",
    y="Victim age",
    color="Charge",
    # title="Add a title here",
    labels={"Age of accused": "Assailant age"},
)

Note that the graph has been created but is not visible since we have not used the fig.show() command yet. This figure will be displayed once we have added a dropdown bar in the following steps.

After creating our initial graph, we can use the update_layout method again to add a dropdown bar. This is a more complex step, since Plotly Express objects' data are nested at many levels under the hood, so we'll need to go a few layers deeper than normal to access the dropdown feature.

Once we have called the update_layout method:

We first need to access the updatemenus parameter: this stores a list of dictionaries, each storing the metadata for various design features.
The only design feature we are currently interested in is the dropdown box, which is stored under the buttons dictionary.
The buttons key stores as its value another list of dictionaries, each representing the options available in your dropdown bar.
We'll need to create two buttons — one for the stacked bar chart and one for the pie chart — so our buttons list will store two dictionaries.
Each of these two dictionaries will need three key-value pairs:
- The first, under the args key, will specify which type of graph to display.
- The second, under the label key, will specify the text to display in the dropdown bar.
- The third, under the method key, will specify how to modify the chart (update, restyle, animate, etc.).

In the example below, we will look at how to use a dropdown bar to toggle between different categories of a variable. Since our initial scatterplot displays the ages of the accused and their victims, we'll add a dropdown bar which allows users to see data points for either a) all cases, b) murder charges only, c) manslaughter charges only, or d) abortion charges only.

To create the dropdown, we need to take the following steps:

Under the label key, the value will specify the text to display in the dropdown bar.
Under the method key, the value will be 'update' since we are altering the layout and the data.
Under the args key, the value (which is another list of dictionaries) will specify which data will be visible (more on this issue below), the title for this graph view (optional), and the titles for the x- and y-axes of this graph view (optional).

You need to enter a list for the visible key: each item in the list indicates whether the data at that specific index should be displayed. In our example, we have partitioned our dataset into three groups: the data corresponding to murder charges, the data for the manslaughter charges, and the data for the abortion charges. As such, our list for the visible key should have three items. Our first button, which represents the first graph displayed to the user, should therefore specify [True, True, True] since we want all charges to be shown in that first view. However, the remaining three buttons will only specify True for one item, because we want to show the data for only one type of crime.

Now let's put this into practice:

# Use .update_layout() method to add dropdown bar
fig.update_layout(
    updatemenus=[
        dict(
            buttons=list(
                [  # Create the 'buttons' list to store a dictionary for each dropdown option
                    dict(
                        label="All charges",  # Add label for first 'view'
                        method="update",
                        args=[
                            {
                                "visible": [True, True, True]
                            },  # This 'view' show all three types of crime
                            {
                                "title": "Victim and assailant ages, Philadelphia homicides (1902-1932)",
                                "xaxis": {"title": "Age of accused"},
                                "yaxis": {"title": "Victim age"},
                            },
                        ],
                    ),
                    dict(
                        label="Murder",  # Add label for second 'view'
                        method="update",
                        args=[
                            {
                                "visible": [True, False, False]
                            },  # Will only show data for first item (murder)
                            {
                                "title": "Dynamic title: victim and assailant ages in murder charges",  # Can change titles here to make the graph more dynamic
                                "xaxis": {
                                    "title": "Dynamic label: age of accused"
                                },  # As above
                                "yaxis": {"title": "Dynamic label: victim age"},
                            },
                        ],
                    ),  # As above
                    dict(
                        label="Manslaughter",  # Add label for third 'view'
                        method="update",
                        args=[
                            {
                                "visible": [False, False, True]
                            },  # Will only show data for second item (manslaughter)
                            {
                                "title": "Another dynamic title: victim and assailant in manslaughter charges",  # New title
                                "xaxis": {
                                    "title": "Another dynamic label: age of accused"
                                },  # New x- and y-axis titles
                                "yaxis": {"title": "Another dynamic label: victim age"},
                            },
                        ],
                    ),
                    dict(
                        label="Abortion",  # Add label for fourth 'view'
                        method="update",
                        args=[
                            {
                                "visible": [False, True, False]
                            },  # Will only show data for third item (abortion)
                            {
                                "title": "More dynamism: ages of accused and victims in abortion charges",  # New title
                                "xaxis": {
                                    "title": "More dynamism: age of accused"
                                },  # New x- and y-axes titles
                                "yaxis": {"title": "More dynamism: victim age"},
                            },
                        ],
                    ),
                ]
            )
        )
    ]
)

fig.show()

Figure 9 (now renamed Figure 8) would go here, and subsequent figures would have to be renumbered.

Creating the dropdown bar in the above example provides users with the ability to isolate (and examine) a given element from the wider visualization. We visited this Plotly feature earlier when noting that double-clicking on an element in the graph's legend will remove it from the visualization. However, the dropdown menu offers an additional advantage: it provides us with the ability to create dynamic headings, which means our titles and labels change depending on which option we have selected from the dropdown box.

The above examples demonstrate that it is very easy to create graphs using Plotly Express and relatively simple to add interactivity such as animation frames and dropdown bars. We will now look at creating graphs with Plotly Graph Objects. Specifically, we will focus on what 'Graph Objects' are, how they work, and when (and why) you might want to create graphs using plotly.go instead of plotly.px.

anisa-hawes commented 11 months ago

Thank you very much, @scottkleinman and @gdmeo!

When you have agreed this revision, Charlotte and I can take care of renumbering the subsequent plots and figures ☺️

gdmeo commented 11 months ago

Hi @scottkleinman -- this is exactly what I had in mind, and thank you so much for putting this together! I think that works really well. My only suggestion is that we add a very brief sentence at the end of the first paragraph to note that we'll be working with a scatter plot, so I've copied in the paragraph below with the suggested added sentence in bold (not to be in bold in the tutorial but just bold here to stand out!).

"Dropdown bars are slightly more complicated than animation frames. They can allow users to switch between a wide variety of display options, including changing colours, lines, axes and even variables. When creating figures with dropdown bars, the first step is to create the initial graph without a dropdown bar (this will be the first graph which your users will see). In this example, we'll be working with a scatter plot which visualises the ages of perpetrators and victims, so we'll create this as follows:"

gdmeo commented 11 months ago

And @charlottejmc I'm now just working on the checklist you provided.

[x] Will send over the author declaration form to the email address
[x] Define the research activity: this lesson supports presenting data
[ ] Define the lesson's topics: python; also data-visualisation if that's an option. Can't see anything else of relevance to the list really -- maybe data-manipulation, but that's not the focal point or aim of the tutorial
[x] Provide alt-text for all figures: I believe these have all been done now, since the only one remaining was the original Figure 8 (which is being removed). Is that the case? (Anisa: Yes, thank you!)
[x] Agree on an avatar. I'm happy with the illustration/graphic you've found, the one with the swan, if that's still alright with you? I wouldn't really know what to use for the visual description though, but I guess words like 'illustrated', 'symmetry' and/or 'plot' could go in there? I'm also happy to find another image though if this one doesn't feel right.
[x] Provide author bio using the template:

- name: Grace Di Méo
  orcid: 0000-0002-3227-8053
  team: false
  bio:
    en: |
      Grace Di Méo is a Lecturer in Criminology in the Faculty of Humanities and Social Sciences at Oxford Brookes University.

[ ] Prepare 2 x social media posts - may have to leave this to @hawc2 as suggested as I have almost zero interaction with SM and wouldn't have the foggiest clue what to write!

Does that tick off everything? Let me know if there's more or if something needs changing :)

scottkleinman commented 11 months ago

Thanks, @gdmeo. I have made the changes.

It's over to you now, @anisa-hawes, to change the figure numbering and remove the extra figures from the images and assets folders.

anisa-hawes commented 11 months ago

Super! Thank you both @gdmeo and @scottkleinman.

Charlotte and I will complete these final tweaks next week.

We are close to being ready to publish this lesson, which is very exciting. Thank you for all the energy you have given.

charlottejmc commented 11 months ago

Hi @gdmeo,

Thank you for your feedback!

I have received and uploaded your copyright agreement and made all the outstanding adjustments to the .md file.

Thank you for suggesting data-visualization: I have now added it to the list of topics we offer!

Hello as well @hawc2 ,

This lesson's sustainability + accessibility checks are now complete.

author(s) bio for ph_authors.yml
name: Grace Di Méo orcid: 0000-0002-3227-8053 team: false bio: en: | Grace Di Méo is a Lecturer in Criminology in the Faculty of Humanities and Social Sciences at Oxford Brookes University.
.md file: /en/drafts/originals/interactive-visualization-with-plotly.md
images: /images/interactive-visualization-with-plotly
assets: /assets/interactive-visualization-with-plotly
original avatar: /gallery/originals/interactive-visualization-with-plotly-original.png
gallery avatar: /gallery/interactive-visualization-with-plotly.png

Promotion:

[x] Template announcement posts
[ ] Prepare x2 posts for future promotion via our social media channels

hawc2 commented 11 months ago

Hey everyone, this looks great to me, thank you for all your hard work getting this to look good. I know it took a lot of revisions, and I appreciate that.

The only minor change I am hoping we can make is to find a way early in the lesson to make it more explicit to the reader that this lesson will guide them through the creation of a series of interactive plots, and specifically that readers of this lesson can access those interactive versions of the plot by clicking on the relevant image or the link provided in the caption. Right now, I could see someone reading through this and not realizing that they can click on the images to pop up an interactive version, especially since not many if any ProgHist lessons currently do this. The captions are easily missed, and it's not really mentioned anywhere else. @gdmeo or @scottkleinman can you take a shot at adding a sentence to clarify that intended way of reading this lesson?

After that, this should be good to move forward with publication. There's still a chance we'll come across minor changes as we stage it for publication, but most of those changes Anisa and I can make

scottkleinman commented 11 months ago

I can take a stab a this. @hawc2, look for an update by the end of your working day.

scottkleinman commented 11 months ago

OK, I have made some changes to Paragraph 4 ("What is Plotly"), but someone should do a quick style/copy edit (@anisa-hawes?).

It would be really cool if we could put the text in bold in an admonition/callout, but I'm not sure if the PH website enables that.

anisa-hawes commented 11 months ago

Thank you, @scottkleinman! I think your addition reads very well.

Good idea! We use Bootstrap Alerts formatting. I've added an alert-warning box which will display in yellow: https://github.com/programminghistorian/ph-submissions/commit/ed8a92333fa7cc6b3cdae712db25f73e1e61df49. I've kept the bold too (we use html inside the Bootstrap), but we can always reconsider this when we are staging the lesson on Jekyll (the final formatting always changes the appearance of features like these). Let me know what you think: the preview is updated.

Best, Anisa

scottkleinman commented 11 months ago

Love it, @anisa-hawes! I'll remember the Bootstrap Alerts for future tutorials.

@hawc2, I think we're ready to proceed.

hawc2 commented 11 months ago

@scottkleinman when you get a chance, can you review the pull request for this lesson (on our main Jekyll repository)? It looked all set to me, but it would be helpful to have your eyes on it too to make sure everything rendered.

@gdmeo I wanted to add that I really love the dataset you chose for this lesson. I know many people in Philadelphia who will be excited to explore it, and it's a great use-case to show what plotly can do!

anisa-hawes commented 11 months ago

Hello @hawc2. @scottkleinman has written to me separately to confirm that he's read the lesson as staged in Jekyll, and is happy with the functionality and rendering of all the plots.

Thank you. A.

anisa-hawes commented 11 months ago

Creating Interactive Visualizations with Plotly is published! 🎉

Congratulations @gdmeo ! ✨ Thank you all for your contributions

Our suggested citation for this lesson is:

Grace Di Méo, "Creating Interactive Visualizations with Plotly," Programming Historian 12 (2023), https://doi.org/10.46430/phen0115.

We appreciate your help to circulate our social media announcements about this lesson among your networks: Twitter/X: https://twitter.com/ProgHist/status/1735269967921086938 Mastodon: https://hcommons.social/@proghist/111578683968533738

I'd be also grateful if you might consider supporting our efforts to grow Programming Historian's community of Institutional Partners. This is a network of organisations across Europe, Canada, North America and Latin America who have invested in our success by contributing an annual membership fee in lieu of subscription.

Institutional Partnerships enable us to keep developing our model of sustainable, open-access publishing, and empower us to continue creating peer-reviewed, multilingual lessons for digital humanists around the globe.

If you think that supporting Diamond Open Access initiatives may be among the strategic priorities of the university or library where you work, please let me know.

You can email me <admin [@] programminghistorian.org>, and I can send you an information pack to share with your colleagues. Alternatively, feel free to put me in touch with the person or department you think would be best-placed to discuss this opportunity.

Sincere thanks, Anisa

hawc2 commented 11 months ago

Congratulations @gdmeo on publishing this great Programming Historian lesson! I bet this one will get a lot of use. Thanks to @scottkleinman for all your work editing this lesson, much gratitude to our reviewers @roblewiscpp and @MBanuelos, and thank you @anisa-hawes and @charlottejmc for your careful work making this complex interactive lesson work on the web! With all your help this lesson was able to really come together, offering a model for how we can teach interactive visualizations on Programming Historian in the future.

programminghistorian / ph-submissions

Lesson Proposal: Creating Interactive Visualizations with Plotly #518

Adding Animations: Dropdown Bars