Layouts you keep

A layout remembers how the columns of one kind of table were mapped: which column holds the well, the name of the top, the measured depth, and what the table does not say (the depth unit). When another file has the same columns, Ophiolite offers the layout. You still choose to use it: a layout is never applied unless you choose it.

Columns are compared by their names, ignoring letter case and spacing. The same columns in another order still match, and the offer says so. Everyone in the project sees the project’s layouts, with the name of the person who made each one and who used it last.

In Workspace

1. Add a table as in A spreadsheet becomes wells and tops. Below Review the import, tick Remember this layout for the project and give it a name (the file’s name is offered). The report says “Layout “Tubbergen tops” remembered for the project.”
2. Add the next file with the same columns. Its row in the report says “This table has the same columns as your project’s layout “Tubbergen tops”, made by Anna de Vries. Reviewed before.” Add this file adds it with the layout; Choose another way opens the mapping with nothing chosen. When several layouts have these columns, choose one first.
3. On the mapping screen, Use a layout fills the rows from a matching layout; every row keeps Change.
4. Sources > Layouts lists the project’s layouts: what each holds, its columns, who made it and who used it last. Open shows the columns and what each one is, and the earlier versions; Use this version again makes an earlier version the layout (a new version; nothing is deleted).
5. Rename, Retire (it is no longer offered for new files; imports that used it keep it in their report) and Use again. Download saves Tubbergen tops.layout.json; Import layouts adds the layouts of such a file to another project, one line per layout: Added, Already here, or why it was not added.

A mapping you saved for a database table can be kept for the project too: on the source’s mapping, Keep this as a project layout. Your own saved mapping stays yours and does not change.

Only people who can edit the project can change layouts; everyone in it can see and download them.

In Python

Bring a table. The examples use three formation tops of the geothermal well HON-GT-01, in a file with the columns Well Name, Top, MD (m), TVD (m), and the same rows with the columns in another order:

table = "tops-F-A.csv"
later = "tops-F-A-reordered.csv"
name = "Tubbergen tops"

Remember how its columns are mapped. The list reads in the same words as Workspace:

from ophiolite.layouts import list_lines

layouts = client.layouts()
columns = [c["name"] for c in client.imports.read(table)["columns"]]
layouts.save("well-tops", name, columns, {"well": "Well Name", "name": "Top", "md": "MD (m)", "tvd": "TVD (m)"},
             declarations={"depth_unit": "m"})
print("\n".join(list_lines(layouts.list())))

Add the table with the layout, by its name, and read the tops back exactly as they were added:

added = client.imports.from_table(table, layout=name)
first = added["run"]["units"][0]
read = client.read_data(first["asset_id"], first["revision"])
print(len(read.tops), "tops, the first", read.tops[0]["name"], "at", read.tops[0]["md"], "m")

A table whose columns are a layout’s is not added until you name the layout or give a mapping. Nothing is added:

from ophiolite.errors import IntegrityConflict

try:
    client.imports.from_table(later, "well-tops")
except IntegrityConflict as refused:
    decision = str(refused)
print(decision)
offered = layouts.match([c["name"] for c in client.imports.read(later)["columns"]])
print([(m["name"], m["how"]) for m in offered])     # [('Tubbergen tops', 'reordered')]

Download the layout, then import the file. In another project (a client for that project) it is added with you as its maker; in the project it came from it is already here:

from ophiolite.layouts import import_lines

path = layouts.export_to(name + ".layout.json", [name])
answer = layouts.import_(path)
print("\n".join(import_lines(answer)))

Retire a layout you no longer use, and offer it again:

layouts.retire(name)
layouts.use_again(name)

layouts.rename(name, new_name), layouts.get(name) (with its history), layouts.keep(connection, table) and layouts.update(name) (a database table’s mapping) work the same way. A refusal is raised with the sentence Workspace shows (“A layout called “Tubbergen tops” already exists in this project. Choose another name, or open that layout to change it.”); the service’s own text is kept as server_message.

On the command line

ophiolite layouts list
ophiolite layouts show "Tubbergen tops"
ophiolite import table tops-F-A-reordered.csv --layout "Tubbergen tops"
ophiolite upload tops-F-A-reordered.csv --attribution "Synthetic" --rights-confirmed --layout "Tubbergen tops"
ophiolite layouts export "Tubbergen tops" --out "Tubbergen tops.layout.json"
ophiolite layouts import "Tubbergen tops.layout.json"
ophiolite layouts rename "Tubbergen tops" "Tubbergen tops 2026"
ophiolite layouts retire "Tubbergen tops 2026"
ophiolite layouts use-again "Tubbergen tops 2026" --version 1
ophiolite layouts keep CONNECTION TABLE --name "Groningen wells"

Without --layout, ophiolite import table and ophiolite upload of a table whose columns are a layout’s add nothing, print “Needs your decision: this table matches the layout “Tubbergen tops”. Add it with —layout “Tubbergen tops”.” and exit 4. --retired lists the retired layouts too; --json prints the service’s answers.

When it is refused

You see	What to do
Only people who can edit this project can change layouts. Ask a project administrator for edit access.	Ask an administrator for edit access.
A layout called “Tubbergen tops” already exists in this project. Choose another name, or open that layout to change it.	Choose another name.
This project keeps up to 100 layouts. Retire layouts you no longer use, or ask a project administrator.	Retire a layout you no longer use.
This layout no longer fits this table: the columns differ. Choose the mapping again.	Map the table yourself, or choose another layout.
This layout changed after you reviewed it. Look at it again.	Open the layout again and review it.
This is not a layouts file from Ophiolite. Choose a file made with “Download”.	Download the layout again and import that file.
This file does not match the layout it was exported from, so nothing was added. Download it again.	The file changed after it was downloaded; download it again.
This layout belongs to a database table in this project, so it cannot be downloaded.	Keep it in the project; database table layouts stay with their connection.