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

[hawc2]

Programming Historian in English has received a proposal for a lesson, "Simulations in historical research: How to create an agent-based model of communication networks" by @merrygin and @maltevogl.

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 @merrygin and @maltevogl to develop this Proposal into a Submission to be developed under the guidance of @digitalkosovski 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 @merrygin and @maltevogl to share their Submission package with our Publishing team by email, copying in @digitalkosovski.

We've agreed a submission date of April. We ask @merrygin and @maltevogl 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, @digitalkosovski will attempt to contact @merrygin and @maltevogl. 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.

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

[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 ✨

[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 @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!