Simulations in historical research: How to create an agent-based model of communication networks about ph-submissions

[digitalkosovski]

Dear @merrygin and @maltevogl, I hope you're both well. I'll be working as editor for this lesson.

In our previous communication by email last week, you asked for some initial feedback on the basis of the first draft you sent on Colab, which you also kindly sent to me in a .md file.

The draft you shared is an excellent starting point for the lesson. Much of it is structured already, the theoretical grounds are clear, and much of the code is written. I would like to offer some comments and advice before you send a full submission package:

1. I would especially advise you to be careful with the 8,000 word-limit, as the first draft is already long, and there are still some sections that need to be written. Part (1) is very interesting and well written, but it is also conceptually dense, so given the word limit you might choose to cut or reduce some parts, and rely instead on references (these will, in any case, be of use for readers who want to delve deeper into the subject after your lesson). One thing that could perhaps render this first part more accessible is the use of one or two images, or conceptual schemes, to illustrate some of your points.

2. Watch out for issues in the structure of the lesson. I noticed a problem with the order of sections in Part 2, with Part 2.2. coming before Part 2.1. Because of this, I couldn't tell whether you mean to discuss mesa or the case study first. As far as I could tell, there is also a Part II, but no Part I.

3. The code gave me some errors when running it on Colab, please double check it in your full submission.

4. You mention that you will use available data from the LetterSampo project, but this doesn't come up again after the introduction. As far as I could tell, the lesson gives the tools to create the simulation model, but you don't actually draw on that data. Have I perhaps missed something here? Or is it only that the model shares some of the same features of that data set? If it is the latter option, I would recommend rephrasing that idea to make it clearer.

These are all initial recommendations based on my first reading of the draft, and I hope that they will be of use to you when working on your full submission. As mentioned in the message above, we will be waiting for the submission package by April. In the meantime, please feel free to write with any questions or doubts. I'm looking forward to reading your full draft, this is a very exciting lesson and I'm glad to be able to give you a hand in the process.

[anisa-hawes]

Thank you for setting up this preview @charlottejmc!

--

Hello Jascha @merrygin and Malte @maltevogl,

I've sent you both invitations to join us as Outside Collaborators here on GitHub. This will give you the Write access you'll need to edit your lesson directly. (There's no need to use the Git Pull Request system in our ph-submissions repository).

Please let us know if you encounter any practical problems as you work with Agustín @digitalkosovski to shape this draft towards its Initial Edit. Charlotte and I are here to help!

Best,
Anisa

[merrygin]

Hi @anisa-hawes @digitalkosovski and @charlottejmc - thank you for setting everything up and providing us with feedback! We will start updating our submission in the coming days.
All best,
Jascha

[merrygin]

Dear all,
Just as a heads-up for you and a self-imposed deadline for us: We are currently finishing up the last edits and are hoping to get everything done for the next steps by Sunday. Thanks for your continued patience!
All best, Jascha

[maltevogl]

Dear @anisa-hawes

thanks a lot for these adjustments! The preview looks really amazing already.
The handle of Aleksandra is @Aleks-Kaye and the one of Raphael is @raphschlatt.

For the missing citations I have to refer to @merrygin .

The in-text references were meant as footnotes for the paragraph text. If that format does not work, maybe they could be converted to endnotes similar to the treatment of citations and referenced with e.g. [^a], [^b] to distinguish from citations?

In Paragraph # 60 there seems to be a formatting error? It starts with ```python id=”tQl5YRxWeonN” “"” and the fourth level header is not picked up. Other then that it looks great!

[digitalkosovski]

Dear @maltevogl and @merrygin,

Many thanks for sending the full draft. After having a quick look at it, I have the impression that you've significantly improved the previous draft (which was very good to begin with), and I expect that there won't be much work to do at this point.

Given that the summer break is approaching, I think we should start the external reviewing process as soon as possible. So my intention is to come back to you next week with a couple of remarks and suggestions so we can speed up the process. Hopefully we can do phases 2 and 3 in just a couple of weeks and launch the external reviews in July already.

Best,
Agustín

[digitalkosovski]

Dear @maltevogl and @merrygin

I've gone through the lesson, and as I expected, I think you've done great work and there are very few suggestions I have before we go to external review.

The lesson is very clear and friendly in spite of the complexity of the subject. You’ve added great references, including some to other PH lessons, and I also appreciate that you’ve added some thoughts and external links concerning the data and the research but in a very efficient way, providing readers with interesting and relevant information, but without overloading the lesson itself with heavy research content.

I just have a few observations and suggestions:

1. In the beginning, you discuss the installation of mesa and of Python. But perhaps it’s also worth mentioning that the lesson also requires solid Python skills. Many readers have notions of Python and many digital historians can code on Python, but my feeling is that a big part of them actually limit themselves to using certain libraries. This lesson requires knowing what classes are about, and it mentions matters of inheritance (child classes, etc), so it does tread on ground that not all historians might be familiar with. We tag lessons according to their difficulty to give readers some orientation in advance, but I still think it would be appropriate for you to include a short comment about the Python skills needed to understand this lesson.

2. Paragraph 47, line 171. You write: “Before we finally start coding, a last couple of remarks have to be made about key concepts in Agent-based Modeling that will reappear in Part 2 in a practical way.” This is probably something that remained from a previous version that had a different structure, because at this point we are already in Part 2. Please correct that in order to avoid any confusion for the reviewers.

3. You discuss data visualization with matplotlib and also state things like “You’ll should see something like the distribution above” (paragraph 77, line 359), but you haven't included any images. Should you maybe include some to illustrate those cases?

4. I see two things that look like formatting problems or missing references in
   paragraph 68, line 265
   and
   paragraph 87, line 410

Maybe @anisa-hawes can confirm?

As you can see, these are all very minor observations, but I think it could be useful to address these things before sending the lesson for external review. If you agree with these observations, I hope you can work on them in the next couple of weeks and send a new version by late June or early July. That will allow us to do the reviews over the summer and contact you again by the end of the summer break.

I hope all of this helps. The lesson is fascinating and to my understanding, extremely useful. I'm very much looking forward to seeing it online.

All the best,
Agustín

[merrygin]

Dear @anisa-hawes @digitalkosovski and @charlottejmc
thanks for your patience so far!
I just submitted our first change to the draft .md of @maltevogl and I. We worked on the original colab file we sent you to be able to test the code and write each other comments, which is why the .md here lay dormant for the past weeks.

We already tried to address some of your feedback, especially that towards structural inconsistencies, the danger of too much text as well as the code not working.

We tried to overhaul Part I to make the methodological introduction to simulations more approachable and less overwhelming. We now try to start at the historical interest for the subject matter and work step-by-step towards why simulations are useful for this. In order to do this, we also slightly changed the structure of the lesson compared to our initial submission.

The code should also be functional now and we extended it to include some visualization elements, especially an interactable interface inside the juptyer notebook. If you'd like to test the functionality of the code, you can try it here in the original colab.

There is still a lot to do, most importantly writing up Part III, cleaning up and finishing the text of Part II and reiterating on Part I, too, including all references / the bibliography as well as setting up a (external) document that systematically summarizes the model and would be a very good end point of the lesson, showing what could be done further with the model.

Unfortunately, all this is likely a bit too much for us to finish by end of April next week. So if it wouldn't be too much of an ask, we would kindly request if we might take a couple more weeks for getting everything ready.

All best,
Jascha

[digitalkosovski]

Dear @merrygin and @maltevogl , thanks for keeping us posted. It all sounds good and I'm confident about your coming submission. As for your request, you can indeed take some extra days/weeks to finish the draft. Keep up the good work!

[anisa-hawes]

Thank you for the update Jascha @merrygin and Malte @maltevogl! I'm just tagging Agustín @digitalkosovski here so that everyone is in the loop.

Please let @charlottejmc or I know if you need any practical assistance. We're here to help ☺️

[anisa-hawes]

Hello Jascha @merrygin, Malte @maltevogl, Aleksandra and Raphael

Hello Jascha, Could you share Aleksandra's and Raphael's GitHub handles with us?

Thank you for your work on this submission!

I've made some adjustments to the file:

• I've adjusted the YAML syntax to align with our system requirements: 6799738
• I've removed the additions <!-- #endregion --> and <!-- #region id=""--> throughout: cce9eb2. This syntax (which I understand is used to expand/collapse code blocks) isn't used in our journal.
• I've removed the additional cell ids and automatic cell links throughout: 642e40e which disrupt our previews.
• I've revised your citations to use the endnotes system: 7e2d5bc

We use The Chicago Manual of Style, 17th Edition Notes and Bibliography system for endnotes. We insert [^1], [^2], etc. into the text, and cross reference these tag in an endnotes list [^1]:, [^2]:.

• I noted that two cited works are missing from the references. These are numbers 16 and 17 in the list: Graham, 2020 and Brughmans and Wilson, 2022. Could you let us know which works these are so we can slot them in?
• Meanwhile, two remaining in-text references are indicated but unlabelled. Could you also advise on these?
  • <a name="cite_ref-1"></a>[<sup>[1]</sup>](#cite_note_1) at line 248 and line 261 of the markdown
  • <a name="cite_ref-2"></a>[<sup>[2]</sup>](#cite_note-2) at line 397 and line 410 of the markdown

You can review the preview here: https://programminghistorian.github.io/ph-submissions/en/drafts/originals/agent-based-model-communication-networks.

If you're happy with the preview now, I think we are ready to hand this on to @digitalkosovski for the Initial Edit ☺️

[anisa-hawes]

Thank you for the clarification about those two references, Jascha @merrygin. I've adjusted the endnote sequence so that these explanatory notes are integrated: 38948f3

Hello Agustín @digitalkosovski. I wasn't certain what these two references were intended to be, but I understand now and we have integrated them into the endnote sequence as numbers 20 and 21. Let us know if this makes good sense to you, or if you'd rather those notes were integrated into the main body text.

[maltevogl]

Dear @anisa-hawes , dear @digitalkosovski

thanks again for the super fast feedback! We can certainly add images. We are just not sure of the integration in the markdown file.
Every run of the notebook generates the visuals, and we can download them independently . For the interface I would suggest a screenshot to show to the readers what to expect.

I also agree with @merrygin , that we should be able to finish the changes this week.

All the best

Malte

[anisa-hawes]

Thank you, @maltevogl.

Please email any additional images to @charlottejmc (programming.assistant[@]programminghistorian.org) in .png or .jpg format (maximum of 840px on the longest edge). Charlotte will process these and slot in the code needed to display them.

If you could also share the accompanying alt-text (visual description of figure image) and caption text, that would be great.

Thank you!

[digitalkosovski]

Fantastic, all good on my end then!
We'll be waiting for the next draft and the pictures then.

[charlottejmc]

Hello @digitalkosovski, @merrygin and @maltevogl,

You can find the key files here:

• .md: /en/drafts/originals/agent-based-model-communication-networks.md
• images: [none]
• assets: [none]

You can review a preview of the lesson here:

• http://programminghistorian.github.io/ph-submissions/en/drafts/originals/agent-based-model-communication-networks

I noticed a couple things when setting this file up, which I've listed below:

• As mentioned by Agustín above, the structure is currently a little confusing to follow. It might help you to know we use heading sizes from ## (largest size) to #### (smallest size) only.
• You used the html code <details> to create a toggle at line 63 – I removed this to keep with our house style. If you want to ensure this part stands out from the rest, we could in-bed it in an information box using alert-info, or simply a grey box using >. I can't tell from the context whether this is necessary here, though.
• I believe parts of the code are missing backticks, which will help to separate it from the main text, and ensure the comments (marked with #) aren't interpreted as markdown headings.

Please feel free to make your subsequent edits directly to the markdown file here on Github!

Thank you ✨

[merrygin]

Thank you for the update Jascha @merrygin and Malte @maltevogl! I'm just tagging Agustín @digitalkosovski here so that everyone is in the loop.

Please let @charlottejmc or I know if you need any practical assistance. We're here to help ☺️

Thanks a lot! The main objective left is to make everything neater (but still short enough) language-wise and to get all the references in. Sadly, it didn't work out entirely today due to a very stubborn sickness, sorry for that! But we are actually almost done, should be finished by tomorrow or Tuesday at latest. I hope this is still fine for everybody!

Have a nice remainder of the weekend!
All best,
Jascha

[merrygin]

Dear @digitalkosovski , @charlottejmc and @anisa-hawes

I've pushed our finished version now, sorry again for the delays!
As I wrote in the commit message, we are still a bit over the word/code-limit, I think, but are unsure which sections would be the most 'shorten-able' ones in your opinion.
Also, we included Aleksandra Kaye and Raphael Schlattmann in the authors section, hoping that this is alright. They both helped us with extensive editing work and comments on the content already for the first version of our submission and for this round again. I (Jascha) forgot to mention them in the first contacts, sorry!

Hope you are all doing well!
All best,
Jascha and @maltevogl

[merrygin]

Oh, also, we used a certain way of inserting references for now, without knowing if this is the preferred one for you. Of course, we'll adapt that to whatever you like us to! Same goes for the actual reference style, which we have not standardized yet, for the same reason.

[anisa-hawes]

Thank you, @maltevogl.

I've removed that cell id id="tQl5YRxWeonN": d7df79c. Apologies for missing that one!

I'm unclear what you mean by footnotes for the paragraph text. We can add in an endnote to provide a note at those two lines, just let us know which works you intended to reference Jascha @merrygin?

I'm confident that the header is display correctly. The typography in our Previews is slightly different than in our published lessons, but you can see how #### Header 4 will render in a published lesson here: https://programminghistorian.org/en/lessons/designing-a-timeline-tabletop-simulator#windows.

[anisa-hawes]

Hello Jascha @merrygin, Malte @maltevogl, Aleksandra @Aleks-Kaye, and Raphael @raphschlatt.

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 Agustín @digitalkosovski will read your lesson, and provide some initial feedback. Agustín will post feedback and suggestions as a comment in this issue, so that you can revise your draft in the following phase (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 (@digitalkosovski)  
Expected completion date? : July 6
Section Phase 3 <br> Revision 1
Who's responsible? : Authors (@@merrygin, @maltevogl, @Aleks-Kaye, and @raphschlatt) 
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.

[merrygin]

Dear @digitalkosovski

thanks for the super fast and useful feedback - I'll have some time tomorrow and on Friday to address it, so we hopefully can keep up your great pace!

Regarding 3., the data visualization: should we drop the images in a particular place and mark the corresponding places to insert them in a certain way? This was an artifact of us building the lesson as a notebook, by the way, but of course the code's results are missing in the pure markdown... we did not think that through, to be honest. Images of the results are totally fine, I think, how about you @maltevogl ?

All best,
Jascha

[anisa-hawes]

That's correct @digitalkosovski. Jascha explained that those two notes were intended to be endnotes so I have integrated them into the sequence.

[merrygin]

Thank you, @maltevogl.

I've removed that cell id id="tQl5YRxWeonN": d7df79c. Apologies for missing that one!

I'm unclear what you mean by footnotes for the paragraph text. We can add in an endnote to provide a note at those two lines, just let us know which works you intended to reference Jascha @merrygin?

I'm confident that the header is display correctly. The typography in our Previews is slightly different than in our published lessons, but you can see how #### Header 4 will render in a published lesson here: https://programminghistorian.org/en/lessons/designing-a-timeline-tabletop-simulator#windows.

Hi @anisa-hawes ,
thanks for your edits also from my side!
I inserted the two missing references now. They must have slipped through in the last edit, sorry!

Regarding the two in-text references at lines 248 / 261 and 397 / 410:
They were intended as footnotes or just comments on the text, i.e., the reference at 248 refers to "footnote" 261, where details about 'RandomActivation' are supposed to be explained. Maybe we could just include these as endnotes instead - or we could try to work them into the main body of the text. We were just thinking that this probably would work and cut down on words at the same time.

[digitalkosovski]

Thank you all for your quick replies.

So if I understand correctly, the issues in paragraphs 68 and 87 that I noticed were just references that had been left inside the text but were meant as footnotes? I've seen notes 20 and 21 and, if I remember correctly, they were in the main body text. Can you please confirm @anisa-hawes ? Everything looks good to me now.

As for the rest, @maltevogl and @merrygin , everything sounds great. We'll be waiting for the new version and the pictures then.

All the best,
Agustín

[anisa-hawes]

Hello Jascha @merrygin, Malte @maltevogl, Aleksandra @Aleks-Kaye, and Raphael @raphschlatt.

What's happening now?

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 @digitalkosovski's initial feedback.

Jascha and Malte already have the 'write access' they need to edit your draft directly. Aleksandra @Aleks-Kaye, and Raphael @raphschlatt, please let me know if either of you need access? 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. With 'write access', you can make direct commits to your file here: /en/drafts/originals/agent-based-model-communication-networks.md. @charlottejmc and I can help if you encounter any practical problems!

When you and Agustín are all 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 (@digitalkosovski) 
All  Phase 2 tasks completed? : Yes
Section Phase 3 <br> Revision 1
Who's working on this? : Authors (@merrygin, @maltevogl, @Aleks-Kaye + @raphschlatt)  
Expected completion date? : July 14
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.