Scope workshop content for November 2024 Seshat get together in Vienna

[edwardchalstrey1]

Google doc agenda link

Content

These have been moved into the Google doc linked above

Discuss, determine, improve, document...

1. The process for "Seshat Expert" data entry - i.e. how the experts use the comment system on the Seshat website, which currently is only used by the RAs, plus whether any general improvements to how this currently works for RAs is needed
2. How to bulk-add data to the database in the various data formats the RA's see as important: Add ability to bulk upload/update data to Seshat database #70
3. How RAs can/should work with the database API going forward and collating suggestions for how to improve the associated Python package
   • This will involve running through the example notebook(s) - I think it will be worth going through this with everyone (can test with Matilda/ Enrico in advance)

Lower priority:

1. Pitches for future big codebase changes that would require effort outside the scope of the current Turing project (and thinking about funding)
2. Any final suggestions for the maps pages/ interface
3. Teach Seshat RAs GitHub skills as per 4th July Edinburgh workshop - see 📚 [Documentation] - Page with links to RA analysis code and project info #111
   • There may not be time for this, and Ed plans to so some 1-1 with Majid separately: Schedule GitHub training #90
4. Improving team communication? It seems hard to know what everyone is working on and how best to contact people. Should we have a slack workspace?

Things the workshop will not cover

Ideas I had about what to include which I am removing:

Not for Vienna

1. Legacy issues with fragile non-reproducible Wiki/CSV -> database transfer issue.
   • Though this may be something Majid and Enrico just need to work though separately from the workshop.
2. Semi-automated process for handling mismatches between Cliopatria and other Seshat data #1 (this may be something to simply highlight and make the RAs aware of rather than to discuss in this workshop)
3. Ed to discuss with RAs how much it's worth putting a lot of effort into completing Visualise spread of Seshat variables on world map edwardchalstrey1/seshat#94
4. How Ed's suggestion for 📚 [Documentation] - How to edit "Cliopatria" borders shape dataset #32 fits into item 1 ^
   • Ed should present this complete workflow including making Cliopatria releases

TODO

• @edwardchalstrey1 Find a time that everyone can do a 2 day workshop in Vienna
  • 11th and 12th November
• Liaise with Daniel K and Jenny R to handle booking everything there
• Write up proposed workshop practical exercises (mostly links to existing docs)
  • I think it's ok to have "too much" to do, so people can go at different paces, or work on different things (e.g. Cliopatria team may want to do those parts and others look at the API)
• Refine the workshop content to get a good balance and update the google doc (linked above) with a timetable, from Pieter:

  The way I see it is that there are two constraining factors: can you timetable sessions we would value the input by Dan and Jim (assuming he is remote) at such a time that they can attend them being in a different timezone? I don’t think all remote RAs need to be there for all sessions. Can you indicate those sessions where their input is most valuable and make clear that it would be great to have them there at these sessions but that there is no expectation for them to join during other sessions?

• Add some "try to do this" at the end of the workshop notebooks
• Define documentation tasks
• Trial run the workshop content with Enrico/Matilda (Turing RAs)
• Make a slide deck to go alongside the google doc and make an introductory presentation to each section of the workshop based on the existing notes in the google doc
• Ask Kalle & Matilda to fill out slides
• Circulate the Google doc
  • Ask them to set up Python, GitHub in advance if they have time, if not, we'll help them
  • Ask them to fill in the Python/Git exp table
  • Check that we'll have the ability to screen share/ present
  • Ensure everyone attending has access to slides and doc
• Nearer the time of the workshop, update the google doc so it works a landing page where people can find the workshop instructions for the practical sessions easily
• Practice giving introductory walkthroughs
  • Talk a bit about how things like stack overflow, google & generative AI can be used for writing code e.g. translating a query from English to pandas
  • In Cliopatria: could talk about when to extract notebook code to separate Python scripts
• If Majid doesn't set up the new site in time, maybe set up the Turing site as a backup for if seshatdata is down during the workshop
  • Set up on the blur branch
  • API works

[edwardchalstrey1]

@kallewesterling let's discuss this next time we meet, but feel free to edit the suggestions above

[edwardchalstrey1]

Note: for any hands on session - knowledge of Python and git/GitHub is likely to be on par with the workshops for mapreader. This likely means an entry-level intro to notebooks is necessary + potentially distributing some pre-reading materials around Python from, say, Programming Historian.

[edwardchalstrey1]

Monday: Working with Seshat data in Python
Setup

For this task you will require Git and Python (and ideally Anaconda) to be set up on your computer. If you don’t have one or more of these, see here for installation instructions. Choose one of the tasks below to begin with.

Task 1: Using the Seshat API in Python to access the Seshat database

Follow the instructions for setting up a conda environment in Python and opening the example notebooks here.
Open the basic_usage notebook and read through, running each code cell in sequence
Hint: Use Ctrl+Enter shortcut to run a code cell and the arrow keys to move up+down
You can then do the same with the camels notebook

Task 2: Exploring the Cliopatria GeoJSON dataset in Python

Follow the instructions for setting up a conda environment in Python and opening the example notebooks here.
Open the cliopatria notebook first and run the first two cells of the notebook, which unzip the GeoJSON, then add colours to it for visualisation. The second of these will take a few minutes to run. Whilst you are waiting…
Open the stats notebook and read through, running each code cell in sequence
Hint: Use Ctrl+Enter shortcut to run a code cell and the arrow keys to move up+down
Check on the progress of the cliopatria notebook and run the subsequent cells. Explore the data visually with the provided Folium plot

Tuesday: Maps, documentation & GitHub
Setup

For this task you will require an account on GitHub. To complete the advanced task, you will also need Git installed on your computer (you probably set this up yesterday already).

Task 1: Feature and bug issues

Spend some time exploring the Seshat World Map (temp link). Try out all of the controls. Make notes if anything doesn’t work or is unintuitive
Click through to polity pages and explore the mini map on those pages. Try out all of the controls. Make notes if anything doesn’t work or is unintuitive.
Click the link to the Seshat GitHub repo issues page
If you noticed any bugs, click the “Get Started” button for a Bug Report and fill out the template. Do this once for each separate bug you noticed.
If you think of ways the map interface could be improved, click the “Get Started” button for a Feature request and fill out the template. Do this once for each separate feature you want to add or change.

Task 2: Documentation issues

Spend some time exploring the project documentation, where we are and what you think is missing.
Decide on what changes you would like to see made. You could for example:
Update the Team page with bios and what you can help others with, key skills and experience.
Update the resources page, or researcher pages, or any other pages you think are missing/incomplete/wrong.
Change the structure of the docs or where to find certain information
Either open a GitHub issue describing the changes that need to be made, or if you are familiar working with GitHub or just feeling ambitious, try the advanced task which involves updating the documentation yourself.
Basic task: Click the link to the Seshat GitHub repo issues page, click the “Get Started” button for a Documentation Improvement and fill out the template. Do this once for each separate page you want to update.
Advanced task: People more familiar with GitHub can follow this guide to make their own pull requests