Review Ticket for Temporal Network Analysis with R

[mdlincoln]

The Programming Historian has received the following tutorial on 'Temporal Network Analysis with R' by @alexbrey. This lesson is now under review and can be read at:

http://programminghistorian.github.io/ph-submissions/lessons/temporal-network-analysis-with-r

Please feel free to use the line numbers provided on the preview if that helps with anchoring your comments, although you can structure your review as you see fit.

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 (http://programminghistorian.org/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 @amandavisconti 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 ombudspeople (Ian Milligan and Amanda Visconti - http://programminghistorian.org/project-team). Thank you for helping us to create a safe space.

[mdlincoln]

I will be checking over this draft for some functional edits so that it's ready for peer reviewers; I'll have this done by July 1st. After that, I'll update here with any further questions before soliciting comments from two peer reviewers.

[mdlincoln]

I have fixed spacing on a handful of lines and made a few tiny typo fixes. Some to-dos for you @alexbrey

• [x] Please commit the data files for this lesson into a new folder at assets/temporal-network-analysis-with-r/ and add text and links to the lesson before the "Static Visualizations" section so that readers will see how to download the data.
• [x] You still need to upload the image files to images/temporal-network-analysis-with-r

[mdlincoln]

@greebie has agreed to serve as one of our lesson reviewers. He'll submit his review no later than September 1. I'm soliciting a second reviewer now.

Just a reminder about our open review process: While we wait for both reviewers to submit their notes, this ticket will also be open to any other feedback from our community. Once we have received both reviewers' responses, the open review period will then be closed. I will summarize the feedback from both reviewers as well as any other input from our community, and work with @alexbrey to decide what further editing the lesson will need.

Please do not make any edits to the lesson draft @alexbrey until we've received both reviews and I've written up my summary - that way I have a chance to prioritize comments and work out any conflicting advice.

I'll update this ticket once I confirm our second reviewer.

[mdlincoln]

@ZoeLeBlanc has agreed to serve as the second reviewer for this lesson.

[greebie]

Hi @alexbrey

My habit in doing these reviews is first to give an overview of my thoughts and then to go over in a little more detail to provide some constructive ideas.

This is a very strong tutorial and there is very little broad advice I can offer. You do a great job of defining your terms, describing the tools and structuring the tutorial around a story using real data. The only broad suggestion I have are: 1) Find ways to precis the writing even more. I wish PH had some basic boilerplate for things like installing packages and libraries. As it stands, since this is a step up from other sna tutorials you may be able to cut some of that work out (paras 14, 17, 18 etc.) 2) I think the conclusion cuts your work short. The tutorial shows us some pretty powerful stuff that turns a general social science tool (sna) and into a powerful method for historical analysis. I'm not knocking sna tutorials because you need to learn static before dynamic, but I think that this tutorial could really be key for those historians who say "so what?" when they see a fuzzy hairball worth of data.

Give us just two or three sentences to summarize the value you think dynamic sna offers a programming historian before you get into the "learn more" stuff.

Thanks again for the tutorial. A joy to read. I will go over the tutorial later this week to cover more detailed suggestions etc. and make sure all the demos are working as they should.

[mdlincoln]

Hi @greebie and @ZoeLeBlanc, just a friendly reminder that your full reviews for this lesson are due by September 1st. We look forward to seeing them!

[mdlincoln]

I've sent a quick reminder note to our reviewers, and will update soon if it looks like we need to push the reviewer deadline.

[ZoeLeBlanc]

Apologies for the delay! Here's my review though it's rather short since this tutorial is pretty close to being ready imo.

So first off I want to commend @alexbrey for an excellent tutorial. You've achieved the difficult balance of teaching methods and concepts while also exploring historical questions, so kudos. I will definitely be assigning and recommending this tutorial to my students! I particularly enjoyed the introduction, which I thought was very accessible, as well as the Marking the Hard Choices section (paragraphs 32-35), where I though you did a great job describing the interpretative work in your dataset, and the Thinking Temporally section (paragraphs 66-68), which I thought really went the step further to make a case for temporal network analysis.

Here's a few nit-picky points (but that's what reviews are for):

• In paragraph 18, you advise installing through the Packages tab, but I was wondering why you wouldn't offer a code snippet with install.packages(...package names) for an easier install option.
• In paragraph 24, you do a great job explaining the difference between bimodal and unimodal but I think this description would benefit from a graph visualizing the difference between bimodal and unimodal networks, and maybe even a graph depicting the transformation from the former to the latter if possible.
• In many of the code snippets, you use the file.choose() function which I really liked and had never used before, but you might want to add a quick aside that this will open a dialog to find the correct file.
• I like the tables showing snippets of the data, but I was wondering why you wouldn't also show a histogram to visualize the distribution of the data? I think first step for any exploratory data analysis is looking at the types of variables and their distributions in a dataset, and I think showing the data in some sort of bar, scatter, or line chart across time will only further your argument about the importance of temporal and dynamic network visualizations. ( I realize you do this edge formation chart later on, so this might be too nit-picky of a point... I'll leave that to your discretion)
• All the datasets need download tags, otherwise you have to copy and paste them into files.
• I really like the forward and backward reach sections but I think it could use a bit more description of what's going on in the graphs.
  • The graph after paragraph 71 might benefit from more visual differentiation between the forward and backward reach, as well as a bit more prose explaining how the reader should interpret that graph. What's useful or noteworthy about the forward and backward reaches of the whole network?
  • Then in paragraph 73 I think before making the next plot you should explicitly state that you're choosing a particular node in the network to visualize its' reaches, rather than mentioning that fact in the captioning. Then you might explain why you chose that particular node (maybe a small hypothesis), and you could even add an additional graph comparing that node's reaches to another node's to bring home the utility of that metric.
• Agree with @greebie that the conclusion was a bit abrupt. I thought in between the first and second paragraph of the conclusion, you might restate briefly some of the take-aways of this tutorial within the frame of your dataset and questions (i.e. exploring this data allowed us to see the following... which then helps us answer the following... ). This might seem a bit tedious but you cover a lot of ground in this tutorial so it might be helpful for the reader to have a brief summary of how everything connects.
• Finally for your list of resources, for python I would list:
  • DyNetx https://dynetx.readthedocs.io/en/latest/
  • NetworkX https://networkx.github.io/documentation/stable/

Please let me know if any of my recommendations were unclear, and I'm happy to provide further comments or clarify. Thanks for the great tutorial, I learned a lot and look forward to seeing it published!

[greebie]

Hello everyone. Given Zoe's comments and my second reading, I do not think I have much new to offer. I know that Matt will go over the tutorial with a fine toothed comb as well, so I'm happy with where it is now.

[mdlincoln]

Thank you @ZoeLeBlanc and @greebie, both! Your comments are invaluable 👏

@alexbrey I will now take a look over both their comments and synthesize a list of revisions for the lesson. Please give me about a week to do this before you start incorporating any changes. I'll post them here by September 12.

[mdlincoln]

@alexbrey Happily, as both @greebie and @ZoeLeBlanc noted, there's very little in the way of substantive content revisions that this lesson needs. It's really beautifully written, and makes quite clear how dynamic network analysis is particularly useful for historical research. The only spots that I think could benefit from some additional content are already mentioned by our peer reviewers:

• [x] I agree with @greebie that you can probably trim out some of the R boilerplate in the paragraphs he mentioned, especially since this lesson assumes that users are already able to run basic R commands.
  • [x] Please add the install.packages(...) code as @ZoeLeBlanc suggests
  • [x] Note about the behavior of file.choose()
• [ ] I don't think you have to further visualize unimodal/bimodal networks, especially since you point to Scott's quite complete post on them. So this would only be a nice-to-have, not a necessity - I leave it to you.
• [x] I think Zoe's suggestion is spot on that the section on forward/backward reach needs just a bit more elucidation. Extending the visualizations along with the text could be an effective way to accomplish this.
• [x] The conclusion could definitely benefit from another paragraph or so to reiterate what we've covered and its significance, particularly WRT comparing network metrics from one timeslice to another, giving them historical meaning that can be hard to see in conventional static SNA.

Zoe also made a great suggestion about forcing the dataset links to download - I will go and edit that on our end when it comes time to push this lesson onto our main repo.

We usually try to finish this round of revisions within four weeks - would you be able to have this done on or before October 10th, @alexbrey? Since the revisions are really quite minor, I'd like to keep this moving quickly. Please confirm in this thread if so.

Looking ahead: after you submit these substantive revisions, I'll do one more copy-editing pass myself and address any final questions that I have, and then we'll publish. I'm really excited to get this out - like both @greebie and @ZoeLeBlanc said, it's a very fine lesson indeed.

[alexbrey]

Thank you @greebie, @ZoeLeBlanc, and @mdlincoln for these comments. I am very grateful for the time and energy that you took to read over the tutorial and make such thoughtful suggestions.

The October 10 deadline sounds reasonable, so I'll work on making these adjustments over the next few weeks.

[alexbrey]

@mdlincoln I think I've made most of the revisions listed above, with the exception of visualizing the bimodal data. I really appreciate that suggestion @ZoeLeBlanc, and I hope there will be other tutorials on PH or elsewhere that address that particular topic, because writing a temporally sensitive projection script was a significant hurdle in my project. Here, however, I think getting deeper into projection would distract from the big picture of introducing TNA methods.

Thanks to you both, and to @greebie again for all of your comments and suggestions. If you have any corrections or comments based on my revisions, please let me know. I'm happy to make additional adjustments.

I do have a concern about how wide the temporal network data tables are. In the preview page they are exceeding the visible width of the main page content, and I'm not sure if that will be a problem when the lesson goes live.

[mdlincoln]

@alexbrey thanks for putting in these edits. I'll take a look and get back with final edits / proofreading by Oct. 17th. Thanks for noting the data table issue, I'll take a look at what we can do about it.

[mdlincoln]

FYI, because it looks like we'll need to be testing out the styling of the many tables in this lesson, I'm going to go ahead and move it over to the main repository now onto the temporal_network_analysis branch and finish the final edits on there.

See https://github.com/programminghistorian/jekyll/pull/1053

[mdlincoln]

This lesson is now live at https://programminghistorian.org/en/lessons/temporal-network-analysis-with-r

Thanks again @alexbrey for a great lesson, and @ZoeLeBlanc and @greebie for your helpful reviews.

[skyebend]

This is a lovely article, but it is odd that it doesn't cite the R package it uses -- especially since it seems to draw very heavily on examples included in the package documentation.

for example > citation('networkDynamic')

gives

To cite package ‘networkDynamic’ in publications use:

Butts C, Leslie-Cook A, Krivitsky P, Bender-deMoll S (2022). networkDynamic: Dynamic Extensions for Network Objects. R package version 0.11.2, https://CRAN.R-project.org/package=networkDynamic.

To cite package 'tsna' in publications use:

Skye Bender-deMoll and Martina Morris (2021). tsna: Tools for Temporal Social Network Analysis. R package version 0.3.5. http://statnet.org/

To cite package ‘ndtv’ in publications use:

Bender-deMoll S (2021). ndtv: Network Dynamic Temporal Visualizations. R package version 0.13.2, https://CRAN.R-project.org/package=ndtv.