Simulating Historical Communication Networks in Python #605
Comments
|
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:
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. |
|
Hello @digitalkosovski, @merrygin and @maltevogl, You can find the key files here:
You can review a preview of the lesson here: I noticed a couple things when setting this file up, which I've listed below:
Please feel free to make your subsequent edits directly to the markdown file here on Github! Thank you ✨ |
|
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, |
|
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. |
|
Dear @anisa-hawes @digitalkosovski and @charlottejmc 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, |
|
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! |
|
Dear all, |
|
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! |
|
Dear @digitalkosovski , @charlottejmc and @anisa-hawes I've pushed our finished version now, sorry again for the delays! Hope you are all doing well! |
|
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. |
|
Hello Jascha @merrygin, Malte @maltevogl, Aleksandra and Raphael
Thank you for your work on this submission! I've made some adjustments to the file:
We use The Chicago Manual of Style, 17th Edition Notes and Bibliography system for endnotes. We insert
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 |
|
Dear @anisa-hawes thanks a lot for these adjustments! The preview looks really amazing already. 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! |
|
Thank you, @maltevogl. I've removed that cell id 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 |
|
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
|
Hi @anisa-hawes , Regarding the two in-text references at lines 248 / 261 and 397 / 410: |
|
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, |
|
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:
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, |
|
Dear all, I just wanted to thank you all for these exchanges, which I think will have a very positive impact on the lesson's final version. I think Alex had a good point with his suggestion for a clearer narrative in the section about historical context. I'll let him judge the last changes, but I feel that things are going in the right direction here. All the best, |
|
Thanks @digitalkosovski, and thanks @merrygin for your edits. The history section looks good now. I missed those ProgHist lessons you cite simply because they aren't labeled as such ("for more on Jupyter notebooks, see as a prerequisite the Programming Historian lesson, "Introduction to Jupyter Notebooks"). But that's the kind of edits we can do during copyediting, mostly to make sure links are explicit with titles to the corresponding articles. With that, @anisa-hawes @charlottejmc, I think this is ready for copyediting! |
|
Hello @merrygin and @maltevogl, This lesson is now with me for copyediting. I aim to complete the work by ~28 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 @digitalkosovski after copyedits are complete. Thank you for your understanding. |
charlottejmc
moved this from 5 Revision 2
to 6 Sustainability + Accessibility
in Active Lessons
|
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 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.
When our Sustainability + Accessibility actions are complete, the Managing Editor @hawc2 will read the lesson/translation 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? : Authors (@merrygin, @maltevogl, @Aleks-Kaye, @raphschlatt)
All Phase 5 tasks completed? : Yes
Section Phase 6 <br> Sustainability + Accessibility
Who's working on this? : Publishing Team
Expected completion date? : 28 Nov
Section Phase 7 <br> Publication
Who's responsible? : Managing Editor @hawc2
Expected timeframe? : ~10 days
|
|
Hello Jascha @merrygin, Malte @maltevogl, Aleksandra @Aleks-Kaye, Raphael @raphschlatt, and @digitalkosovski, 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 all happy, we can merge in the PR. |
|
Hello @hawc2, This lesson's sustainability + accessibility checks are in progress.
Publisher's sustainability + accessibility actions:
Authorial / editorial input to YAML:
Files we are preparing for transfer to Jekyll:
Promotion:
Publisher's post-publication tasks:
|
|
Hi @merrygin, @maltevogl, @Aleks-Kaye, and @raphschlatt, I've had a look through the British Library and found a few images which reminded me of the theme of writing/sending letters: Do let me know what you think! You're very welcome to suggest alternatives if you prefer. |
|
Dear all, I'm glad we're approaching publication. Thanks to @charlottejmc for all the hard work. Reviewers were Luling Huang @hluling and Leif Scheuermann @LeifSch. I would tend to define the lesson as difficult. We could put it as intermediate, because it’s very well explained and clear, and there are some previous PH lessons that facilitate many of the tasks. But the lesson presents challenging concepts and more importantly, it demands a rather advanced use of Python, with a good comprension of how classes work, This makes me think it falls a bit more on the side of difficult lessons. But I'd like to hear your thoughts about this. As for the topics, and considering the specificity of the method, I'm wondering if we should add a new topic, whether "Simulation" or "Agent-based modelling"? What do you think @hawc2 ? |
|
@digitalkosovski it's tough to decide, but I'm leaning towards Advanced rather than Intermediate difficulty for this lesson. As you say, this lesson requires advanced use of Python, in particular knowledge of how classes work. More importantly, this lesson doesn't really teach what classes are in Python or how they work (classes are explained but at a higher model for simulation modeling, as far as I can tell). If the lesson had been devoted to teaching those fundamentals, I'd give it an Intermediate, but since it assumes knowledge of pretty advanced programming to do the methodology, which is difficult unto itself, I'd be in favor of giving this one the highest difficulty rating. With that said, ideally in the abstract we can still highlight how this lesson is 'introducing' complex methodologies to make it seem inviting to readers. For topics, we could afford to revamp our list of topics anyway, but I might be inclined to keep it more generic if we add a topic and just make it "modeling"? I'm not sure if we'll have many other lessons for a while that would fit under the category of "simulation" or "agent-based modelling" but I'd defer to @anisa-hawes on that. |
Dear @charlottejmc , pictures look good to me! Technically, early modern pictures would be a better fit since we originally thought about the model through the lense of / based on data about the republic of letters, but I reckon those will be harder to find & incorporate and also it doesn't play as much of a role in the finished lesson now. In any case, I'm happy about your choice! Re author bios: Should we just append the existing yaml with our bio snippet, or send you each a new file? Also, I just sent you the copyright and publishing rights doc. All best! |
|
Dear @merrygin, @maltevogl, @Aleks-Kaye, and @raphschlatt, An early modern picture is a really great idea! Both your suggestions are lovely, but I would choose this one because it is in the public domain, which makes it easier to use, and I believe it will look better as a small, greyscale thumbnail on our site. You can simply send us your author bios in a comment here below, by copy and pasting this format (you don't need to change Thank you very much for the copyright agreement, which I have received by email. ⭐ As well as your author bios, the last thing we need from you is a short lesson abstract: 1-2 sentences which quickly and broadly tell the prospective reader what they can learn from the lesson. To make the most of the available space, it is usually more interesting not to repeat the lesson title word for word. @hawc2 also suggests above to "highlight how this lesson is 'introducing' complex methodologies to make it seem inviting to readers". Thank you very much @digitalkosovski and @hawc2 for your insights on the difficulty level. I've set it to 3 (advanced) and I'll discuss the topics with Anisa too. As for the Activity, shall we say 'analysing'? |
|
|
Dear Charlotte and Everyone,
I'm including my details below. I also like the picture chosen.
Thank you and best wishes,
Aleks
- name: Aleksandra Kaye
orcid: 0000-0001-9754-4191
team: false
bio:
en: |
Aleksandra Kaye is a Postdoctoral Researcher at the Department of Structural Changes of the Technosphere at the Max Planck Institute of Geoanthropology, Jena, Germany.
|
|
⭐ A suggestion for the abstract: "This lesson will introduce you to core concepts, methodologies, and discussions surrounding simulation methods for historical inquiry and in particular Agent-based modeling. You will also be introduced to the basic elements of programming a simulation model by building a model of historical letter exchange with the python library mesa." Is this the right direction? Too dry? Something missing? |
|
This reads well to me Jascha @merrygin - thank you. What do you think, Alex @hawc2? -- Hello @raphschlatt, When you have a moment, could you share a one-line bio using this template? -- In the meantime, Charlotte and I will create the new |
|
@merrygin and @digitalkosovski, I've been talking with @anisa-hawes, and one thought we we're hoping to hear your opinion on was a change to the title to this lesson. Ideally the title gives some sense of the type of software and data used in the lesson. We we're thinking the lesson title could be simplified and clarified to something like "Simulating Historical Communication Networks in Python". What do you thnk would work? |
I think this is a great idea and I also had the feeling that the title might be a bit too long like this. I think "Simulating Historical Communication Networks in Python" would also fit the general style of other lessons' titles very well. I'd be very happy with that suggestion. What do you think, @maltevogl ? |
|
I really like this idea to change the title. It should be shorter to be more inviting. Thanks for the suggestion. I also like the short abstract text you suggested @merrygin |
Yes, here it is: name: Raphael Schlattmann And I also like the title suggestion. |
charlottejmc
changed the title
|
Thank you all for your input! I have updated the lesson title in this issue, as well as in all the necessary files. Please note that the lesson slug is now |
anisa-hawes
moved this from 6 Sustainability + Accessibility
to 7 Publication
in Active Lessons
|
Thank you all. I will prepare this lesson for publication in early January ✨ We are in the process of setting up the new |
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:
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:
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.
The text was updated successfully, but these errors were encountered: