Backend interface for Arch14CZ - Czech Archaeological Radiocarbon Database

Created on 14. 12. 2021

Table of Contents

1. About Arch14CZ
   1. Database Schema
2. Installation
3. Usage
   1. Connecting to a Backend Database
   2. Data Entry
   3. Ordering Relative Datings
   4. Importing Excel Data
   5. Choosing a Radiocarbon Calibration Curve
   6. Publishing Data
   7. Restoring from Backup
4. Developer Notes
   1. Preparing the Virtual Environment
   2. Cloning the GitHub Project
   3. Building a Windows Executable
5. Contact
6. Acknowledgements
7. License

Backend graphical user interface for Arch14CZ - Czech Archaeological Radiocarbon Database.

Original repository of the author: https://github.com/demjanp/arch14cz_backend.

For the frontend interface see the arch14cz_frontend project.

Please cite this sofware as:

Demján, P. 2021: Arch14CZ - Backend, GitHub repository, Available at: https://github.com/ARUP-CAS/aiscr-arch14cz-backend

The database is be based on the Deposit graph model, comprised of Classes representing different types of data, Descriptors representing attributes of the particular records, Objects representing those unique records (data points) and Relations representing connections between these records.

Database schema: Classes (on grey background), their Descriptors (in frames) and Relations between them.

For a Windows installer see:

https://github.com/ARUP-CAS/aiscr-arch14cz-backend/releases/latest

The Arch14CZ backend interface is used to connect to the backend database, enter new data or import it from an Excel file, order relative datings and publish the data to the frontend database.

Note that after adding an entry or entries with a new relative dating, appropriate chronological relations have to be added to it before it can be published to the frontend database.

To connect to a backend database, use the command Backend → Connect and select a data source. The data source can be either a local file (Pickle and JSON formats) or a PostgreSQL database.

You can create a new Pickle or JSON database by entering its path (e.g. C:/data/data.pickle) and clicking Create.

You can create a new PostgreSQL database by entering the connection details (a blank database has to be already created on the server, for example using pgAdmin), choosing a new identifier and clicking Create.

PostgreSQL Relational is a special format to preserve maximum compatibility of Deposit, which is a graph database, with relational databases. In this format relations are stored using join tables which can cause loading and saving to take longer.

Note that when using a PostgreSQL backend, you need to specify a local folder. In this folder a backup will be stored each time you save the database if the option Backend → Backup after every save is enabled.

1. Before entering new data, ensure that the Arch14CZ schema is created in the current database via the command Backend → Create Schema.
2. Open the backend database using the command Backend → Open.
3. Click on C14 Form on the User Tools toolbar.
4. Fill in the form (see the Import section for details on different fields) and click Submit.

Example of a filled entry form.

All field groups except Relative Dating and Source have a drop-down list, with the possibility to look up if an entry is already present in the database and use the Fill button to fill it in.

For the frontend database to function properly, relative datings have to be ordered. This is done by creating before type relations between the relative dating entries, which indicate that one relative dating is earlier (before) another. Based on these relations, the Arch14CZ application can then calculate ordering of the dates which can be used to specify a relative dating range when querying the database.

1. Open the backend database using the command Backend → Open.
2. Open the Relative Dating Class by double-clicking its name in the left navigator pane. Alternatively, you can click on the Relative Datings - General tool on the User Tools toolbar to list only general datings, without specified phases.
3. Click the Graph tab on the query window.
4. Find an entry that is not yet linked to at least one other entry. All entries should have at least one link an earlier and one link to a later dating (as far as there is one).
5. Find the closest dating which is later than the selected one and create a before type relation to it as shown in the animation:
6. In a similar way, create a before relation between the closest earlier entry and the selected entry.
7. Repeat until all entries are connected in a chronological sequence.

Detailed relative datings where e.g., a phase of a culture is specified, can also be linked to more general datings by a contains relation. For example the dating Linear Pottery Culture can contain the dating Linear Pottery Culture, phase IIa. A dating which only has a contains relation will be ordered in the same way as the dating by which it is contained.

The command Backend → Update Datings automatically links all general and detailed datings by a contains relation. For example Linear Pottery Culture, phase IIa would generate two linked datings Linear Pottery Culture → contains → Linear Pottery Culture, phase IIa.

Data can be imported from an Excel (.xlsx) file via the menu Backend → Import Excel Data. For an example, see import_sample.xlsx.

The file has to contain the following columns:

1. Lab Code The laboratory code is unique for each sample and serves to identify it. It also carries information about the laboratory that measured the sample.
2. C-14 Activity BP: C-14 measurement in radiocarbon (uncalibrated) years BP
3. C-14 Uncertainty 1 Sigma: 1-sigma uncertainty of the measurement
4. C-14 Method: AMS or conventional
5. Delta C-13: Delta C-13 measurement
6. C-14 Analysis Note
7. Country
8. Cadastre
9. Cadastre Code: Code of the cadastre (see https://www.czso.cz/csu/rso/katastralni_uzemi_rso).
10. District
11. Site Name Unique name of the site where the sample was collected.
12. Site Coordinates: WGS 84 standard, format XX.XXXXXXXN, XX.XXXXXXXE
13. Site Note
14. Fieldwork Event ID Identifier of a Fieldwork Event in the Archaeological Map of the Czech Republic associated with the Site
15. Activity Area: Type of the archaeological activity area according to the AMCR dictionary. Validated against activity_area.csv.
16. Feature: Type of the archaeological feature according to the AMCR dictionary. Validated against feature.csv.
17. Context Description Description of the position of the sample within the feature.
18. Context Depth cm: Depth at which the sample was retrieved.
19. Context Name: Unique identifier of the context within the site (e.g., Feature 123).
20. Relative Dating Name 1: Relative dating of the context, as detailed as possible in the format "[General Dating], [phase]" (e.g., Lengyel Culture, phase I). The general dating is validated against relative_dating.csv.
21. Relative Dating Name 2: Additional relative dating.
22. Sample Number: ID assigned by the submitter of the dated sample.
23. Sample Note Includes collagen values and other accompanying measurements.
24. Material Name General type of the material of the sample (e.g., animal bone, charcoal). Validated against material.csv.
25. Material Note Detailed description of the material (e.g. sus scrofa, triticum monococcum)
26. Reliability: Reliability of the C-14 dating in respect to the archaeological context. Possible values:

    no problems declared
    in contradiction with archaeological chronology/sequence
    no archaeological finds associated
    context disturbation
    other problems
    sample contamination
    

27. Reliability Note
28. Source Description: Citation of the source.
29. Source Reference: Reference to page or figure.
30. Source URI: DOI or aleph link (where applicable).
31. Source Acquisition: Original source of the data (Arch14CZ, C14.sk or other database)
32. Submitter Name In the format [First name] [Last Name]
33. Submitter Organization
34. Public: 1 or 0, indicates whether the date can be published (if set to 0, the values of C-14 activity and uncertainty will be set to -1 when publishing to the frontend database)

The software is supplied with the IntCal20 calibration curve by Reimer et al. ¹.

You can download the latest calibration curves from the IntCal website.

To load the calibration curve:

1. In the Arch14CZ program, open the menu Settings and click on Calibration Curve.
2. Select the file containing the calibration curve data.

To publish data to the frontend database, follow these steps:

1. Connect to the frontend database using the command Frontend → Connect.
2. Enter the connection details (a PosgreSQL database must already exist on the server).
3. Publish the database using the command Frontend → Publish.

This will automatically calculate the order of relative datings and 95% ranges of calibrated dates for each C-14 date. The data will be then uploaded to the frontend database.

If the option Backend → Backup after every save is enabled, a backup copy of the database is stored before each save. You can return to a previous version of the database simply by loading one of the backups in the Arch14CZ - backend application.

Backups can be found in the subdirectory _backup of the local folder, which can be accessed by clicking the link next to Local Folder on the main interface.

To save a database restored from a file format in PostgreSQL format, open the Deposit inteface via the menu Backend → Open and save it via the menu Data → Save As PostgreSQL.

Arch14CZ - Backend requires Python 3 and a Windows environment. To prepare a Python virtual environment for development:

1. Open a terminal or command prompt window.
2. Navigate to the Arch14CZ - Backend root directory:

cd [path to local Arch14CZ - Backend dir]

3. Create the virtual environment:

python -m venv [VE dir name e.g. 'venv']

4. Activate the virtual environment:

venv\Scripts\activate.bat

5. To exit the virtual environment:

deactivate

To clone the aiscr-arch14cz-backend GitHub project, follow these steps:

1. Make sure you have Git installed on your computer.
2. Open a terminal or command prompt window.
3. Navigate to the Arch14CZ - Backend root directory.
4. Run the following command:

git clone https://github.com/ARUP-CAS/aiscr-arch14cz-backend.git

5. The repository will be cloned to a new directory named aiscr-arch14cz-backend in your current directory.
6. Change into the newly created directory:

cd aiscr-arch14cz-backend

7. To install dependencies run the following command:

pip install -e .

8. To start the GUI run the following commands:

cd bin
python start_arch14cz.py

1. Make sure you have InstallForge installed on your computer.
2. Update absolute paths in installer\arch14cz_installer.tpl in the following sections:

[Graphics]
	Wizard image
	Header image
[Build]
	File
	SetupIconPath
	UninstallIconPath

3. Update virtual environment path in installer\arch14cz.spec in the part pathex=['..\\venv\\Lib\\site-packages'],.
4. Activate the virtual environment.
5. Execute the following commands once per virtual environment:

python -m pip install --upgrade build
pip install pyinstaller

6. Deactivate the virtual environment.
7. Run build.bat.
8. Run InstallForge and open the file installer\arch14cz_installer.ifp.
9. Use the Build command in InstallForge to build the installer.

Peter Demján (peter.demjan@gmail.com)

Institute of Archaeology of the Czech Academy of Sciences, Prague, v.v.i.

Development of this software was supported by OP RDE, MEYS, under the project "Ultra-trace isotope research in social and environmental studies using accelerator mass spectrometry", Reg. No. CZ.02.1.01/0.0/0.0/16_019/0000728.

This software uses the following open source packages:

• Deposit
• Deposit GUI
• NetworkX
• NumPy
• openpyxl
• Psycopg
• PySide2
• Qt
• SciPy

This code is licensed under the GNU GENERAL PUBLIC LICENSE - see the LICENSE file for details