📚 [Documentation] - How to edit "Cliopatria" borders shape dataset

[edwardchalstrey1]

Pre-requisites

• 📚 [Documentation] - How to use the Seshat website edit and "Private comment" system to make and discuss data edits #112

Section of Documentation

Developer, RA

Description of Improvement

Update: A draft process exists: https://seshat-global-history-databank.github.io/seshat/researcher/cliopatria.html#requesting-edits-to-the-cliopatria-dataset

We need to document the way in which the Cliopatria borders dataset can be edited via suggestions from the Seshat project website.

• Determine whether Cliopatria will have it's own GitHub repo under the Seshat-Global-History-Databank org - Update: Yes - see Create Cliopatria repo and documentation for it #60
• We need to figure out the full process for making edits and document it. Could be something like:
  • Based on an edit request that the Seshat admin fields via the website, the admin opens an issue on the Cliopatria repo according to an issue template. The template should be specific enough that an RA can understand the issue and make the required edits, e.g. fields for the polity name, year etc. An RA who knows how to make updates to Cliopatria should get auto-assigned to the issue. Use the Seshat private comment system
  • The RA uses the same process/tools they used for creating Cliopatria to make edits and releases a new version via the Cliopatria repo (if the RA disagrees use either GitHub comments on the issue or whatever method already exists in the Seshat website for handling/discussing edit disputes)
  • The RA releases the new version of Cliopatria and asks the Seshat developer(s) to update the site with the new version

Question: once Seshat uploads a stable v1 release of Cliopatria, will future versions of Cliopatria be:

• Created downstream of edits coming via Seshat, with the Seshat database becoming the source of truth for our borders dataset or
• Will Seshat intend to consume future versions/releases of Cliopatria which are updated independently of Seshat or
• Some combination of these

TODO

• Add draft process to docs detailing how it could work
• Discuss with Jim B
• 📚 [Documentation] - Better docs on how to use Cliopatria #166
• Cliopatria GitHub edit template cliopatria#13
• Discuss this with the project team in Vienna workshop

Benefits of Improvement

Clear ways of working for the project

Additional Context

As of 16th July 2024 there is yet to be a public release of Cliopatria. The intention is to release it soon alongside a publication, now that the GeoJSON format has been stabilised and further updates are only related to content rather than structure. Seshat is already set up to load Cliopatria into a table in the database for visualisation in the Django app.

[edwardchalstrey1]

Currently, the edit process will be simply to make use of the existing request system for RAs, but they can quote the Shape ID when suggesting an edit

[edwardchalstrey1]

Update: Originally I had planned to work through this in the Vienna workshop, however I now think it would be better to work through this separately on a call with Jim

Questions

• In the Cliopatria edit system, how to people check their edits?
• Can we show different versions of Cliopatria in Seshat based on different people's suggestions? Would different versions be in Cliopatria GeoJSON or just in the Seshat database?

[edwardchalstrey1]

More questions, notes, todos after meeting with Jim on Monday 4th Nov '24

• Do we need docs on the Cliopatria GeoJSON structure?
  • could include things like Jim's slide on Jigsaw constraint
  • Polygon edit method is something custom Jim has built, rather than a particular software package or GUI
• Crucially, we cannot determine the release process for Cliopatria until its determined whether we want to encode alternatives and disputes
  • Idea: disputes could be shown on polity pages, but not world map. This avoids the Jigsaw constraint.
• Where do the comments on suggested edits take place?
  • Do they work within the main site or a test site, or within a local dataset?
  • How would RAs respond to a Seshat Expert with the suggested fix for their comment?

[edwardchalstrey1]

How to repurpose the ShapeID (or PolygonID field in Seshat when this becomes available in Cliopatria)

Ed:

Yes, currently I just have a counter as the ID. I agree that for a better unique ID for each polygon, we may as well use the polity name within that for clarity. In fact, thinking about it some more, I think it may make sense to simply use the combination of Name, FromYear and ToYear as the ID for each polygon.

In the Seshat editor view, instead of getting the editor person to select a shape ID, I can make it so they must select the Cliopatria polity name and designate a year range to make the edit for. By default, this is the range of the first shape for that polity, but you can choose the range of a later shape, or a custom range within the whole polity year range.

This way we don’t need to add a PolygonID field for the Cliopatria GeoJSON at all and it will still be clear exactly which polygon(s) an edit is being suggested for. Does that make sense?

Jim:

Unfortunately from experience we found this wasn’t sufficiently precise for editing work. For some polities where a single polygon represents its extent this works but quite often a polity can have multiple polygons for the same year or set of years (like the Greek islands

Ed:

Hmm ok, then I think we do need a PolygonID, but it could go either of 2 ways:

1. Do as you suggest, but if a polygon gets a new “owner” polity in a later year, you give it a new PolygonID. E.g. “PolityX/3” in year 100 might be a duplicate of “PolyonY/7” in year 120. Adjusting one of these wouldn’t affect the other.
2. Polygons have a unique ID that is completely independent of polity name. A polygon that had the PolygonID “1234” from the polity named “PolityX” in year 100 which became a part of “PolityY” in year 120, would still have the PolygonID “1234” (or perhaps a hash character string would be better than an integer?). Any adjustment to the shape would result in a new PolygonID. This could be handy to track shapes that change ownership?

I think in either case, a Seshat researcher/expert editor would reference a combination of PolygonID(s), polity name, FromYear and ToYear when suggesting the edit to make.

Jim:

I favor the first option as it is succinct (no hash string that might be hard to copy/paste into email, etc.). Let’s give that a go and see how awkward it all is when RAs have to work with it, jim

So we can use the existing ShapeID field but update the command script to populate it from Cliopatria