Simulations in historical research: How to create an agent-based model of communication networks #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 @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, |
|
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. |
|
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. I also agree with @merrygin , that we should be able to finish the changes this week. All the best Malte |
|
Thank you, @maltevogl. Please email any additional images to @charlottejmc (programming.assistant[@]programminghistorian.org) in If you could also share the accompanying Thank you! |
|
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, |
|
That's correct @digitalkosovski. Jascha explained that those two notes were intended to be endnotes so I have integrated them into the sequence. |
|
Fantastic, all good on my end then! |
|
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
|
|
Dear @anisa-hawes , Thank you for your message. Yes, please could you give me access. Best wishes, |
|
Dear <https://github.com/anisa-hawes> @anisa-hawes ,
Yes, I would also like to have access.
Best,
Raphael
Von: Aleks-Kaye ***@***.***>
Gesendet: Freitag, 14. Juni 2024 09:20
An: programminghistorian/ph-submissions ***@***.***>
Cc: Raphael Schlattmann ***@***.***>; Mention
***@***.***>
Betreff: Re: [programminghistorian/ph-submissions] Simulations in historical
research: How to create an agent-based model of communication networks
(Issue #605)
Dear @anisa-hawes <https://github.com/anisa-hawes> ,
Thank you for your message. Yes, please could you give me access.
Best wishes,
Aleks
-
Reply to this email directly, view it on GitHub
<#605 (comment)
ent-2167394968> , or unsubscribe
<https://github.com/notifications/unsubscribe-auth/ATUNM5DX5ZBDMJWK7YVRGUDZH
KKTLAVCNFSM6AAAAABE52QKKKVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDCNRXGM4TI
OJWHA> .
You are receiving this because you were mentioned.
<https://github.com/notifications/beacon/ATUNM5EISBG6BQCG6HGYPJDZHKKTLA5CNFS
M6AAAAABE52QKKKWGG33NNVSW45C7OR4XAZNMJFZXG5LFINXW23LFNZ2KUY3PNVWWK3TUL5UWJTU
BF7JJQ.gif> Message ID:
***@***.***
***@***.***
… >
|
|
Thank you @Aleks-Kaye and @raphschlatt. I've sent you both invitations so that you can join as Outside Collaborators. As I mentioned, 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. When you have accepted the invitation I've sent you, you will be able to make direct commits to your file here: /en/drafts/originals/agent-based-model-communication-networks.md. @charlottejmc and I are here to help with any practical questions 🙂 |
|
Dear @digitalkosovski @anisa-hawes and @charlottejmc I just pushed the changes in response to your feedback and sent the images to Charlotte. All best! |
|
Ah, I just got the email with the images back with an error. The address might be an issue with the address? I used "programming.assistant[@]programminghistorian.org" - should that work in theory @charlottejmc ? |
|
Sorry @merrygin, if you remove the brackets around the |
|
That I actually already did @charlottejmc :D So I did use '[email protected]' |
|
Apologies @merrygin! This is my mistake! 😅 |
|
No worries! :D I've sent it to the other address now. |
|
Hello @merrygin, Thanks so much for your patience with the email address. I received the files you sent! I've renamed them according to our convention (in order of appearance in the text) and uploaded them to your lesson's image folder, here. Thanks also for helpfully providing the captions and alt text in the correct spots. Please do take a look at the edits I made in this commit, to help solve a number of queries I've outlined below:
Alt text is a descriptive element that enables screen readers to read the information conveyed in the images for people with visual impairments, different learning abilities, or who cannot otherwise view them, for example due to a slow internet connection. It's important to say that We have found Amy Cesal's guide to Writing Alt Text for Data Visualization useful. This guide advises that alt-text for graphs and data visualisations should consist of the following:
What Amy Cesal's guide achieves is prompting an author to reflect on their reasons for including the graph or visualisation. What idea does this support? What can a reader learn or understand from this visual? The Graphs section of Diagram Center's guidance is also useful. Some key points (relevant to all graph types) we can take away from it are:
For general images, Harvard's guidance notes some useful ideas. A key point is to keep descriptions simple, and adapt them to the context and purpose for which the image is being included. Would you feel comfortable making a new draft of the alt-text for those figures? This is certainly a bit time-consuming, but we believe it is very worthwhile in terms of making your lesson accessible to the broadest possible audience. We would be very grateful for your support with this. Thank you very much again, and please ask @anisa-hawes or I if you need any further support. |
|
Dear @charlottejmc , Indeed, although I do know in principle what alt-texts are for, I was really unsure how to approach them. The guidance in the link was really helpful and I hope the alt-texts are now a bit more sensible! I hope my changes address your queries to your satisfaction, otherwise I do have time this week to try again! All best, |
|
Dear @maltevogl @merrygin @Aleks-Kaye and @raphschlatt Thank you for all your hard work. The lesson looks good to me and at this point I think we can go on to external reviews. Best, |
|
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 4: Open Peer Review. This phase is an opportunity for you to hear feedback from peers in the community. Agustín @digitalkosovski will now invite two reviewers to read your lesson, test your code, and provide constructive feedback. In the spirit of openness, reviews will be posted as comments in this issue (unless you specifically request a closed review). After both reviews, Agustín will summarise the suggestions to clarify your priorities in Phase 5: Revision 2. %%{init: { 'logLevel': 'debug', 'theme': 'dark', 'themeVariables': {
'cScale0': '#444444', 'cScaleLabel0': '#ffffff',
'cScale1': '#882b4f', 'cScaleLabel1': '#ffffff',
'cScale2': '#444444', 'cScaleLabel2': '#ffffff'
} } }%%
timeline
Section Phase 3 <br> Revision 1
Who worked on this? : Authors (@merrygin, @maltevogl, @Aleks-Kaye, @raphschlatt)
All Phase 3 tasks completed? : Yes
Section Phase 4 <br> Open Peer Review
Who's working on this? : Reviewers (@LeifSch + @hluling)
Expected completion date? : Sept 5
Section Phase 5 <br> Revision 2
Who's responsible? : Authors (@merrygin, @maltevogl, @Aleks-Kaye, @raphschlatt)
Expected timeframe? : ~30 days after editor's summary
|
|
Dear all, During previous phases, I provided initial feedback on this lesson, then worked with Jascha @merrygin, Malte @maltevogl, Aleksandra @Aleks-Kaye, and Raphael @raphschlatt to complete a first round of revisions. In Phase 4 Open Peer Review, we invite feedback from others in our community. Welcome Leif Scheuermann @LeifSch and Luling Huang @hluling. By participating in this peer review process, you are contributing to the creation of a useful and sustainable technical resource for the whole community. Thank you. Please read the lesson, test the code, and post your review as a comment in this issue by September 5. You have expressed your intention to finish sooner, but you can perfectly take some extra days and turn your reviews by early September if needed. Reviewer Guidelines: https://programminghistorian.org/en/reviewer-guidelines A preview of the lesson: Notes:
|
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: