Migration guide v0 to v1¶

This is a guide to help migrating scripts and notebooks using the “old” v0 API to the newer v1 API. Please also refer to the v1 API overview for more information. These examples use the 0.2.X SDK.

Concepts¶

The v0 API was the first implementation of the Cognite Seismic API. It is centered around the concepts of files which have a 1:1 correlation to actual SEGY-format binary files. As the API has moved beyond working only on physical files in Cloud Storage, supporting multiple storage formats and also read-only views of seismic data, this was an unfortunate restriction. Therefore, we implemented a backwards-incompatible v1 API that contains these features.

Along with the model changes described below, the v1 API uses numeric identifiers as internal object ids, including in cases where the v0 API used string uuids. All existing objects have been given new internal ids while retaining uuids.

The following is a mapping from v0 objects to v1 objects.

v0 File -> v1 SeismicStore¶

We introduce a new object, the seismic store. A seismic store simply represents a set of trace data, stored in a specific backend. While currently all seismic stores are created from files, this does not necessarily have to be the case. Seismic stores have the same kind of metadata that files had; file objects still exist but are used solely as a reference into a cloud storage bucket and are not the sole way of identifying a seismic dataset. Seismic stores also support all operations files have, including coverage, headers, and trace queryies.

We currently support two storage backends, Google Cloud and BigTable. The former is low speed low cost, and the latter is high speed high cost. We aim to introduce more storage backends tailored to specific usecases.

Note that file objects still exist in the v1 API, but they are solely used for managing ingestion.

v0 Survey -> v1 Survey¶

There have been no drastic changes for the Survey endpoints. v1 Surveys support listing seismic stores and seismics (described below) as well as files.

The following are new objects.

Seismic¶

Seismics are no-copy views into seismic stores. Once defined, either via a polygon to “cut out” from the origin seismic store or an explicit trace-by-trace mapping, they cannot be modified. Seismics can be assigned to partitions, and it is possible to grant access to users restricted to particular partitions. Thus, they serve as the most granular unit of access control.

Partition¶

Data partitions are used for access control. If you don’t use multi-tenant, you won’t need to use partitions. Each seismic has one corresponding partition, and if a user is restricted to particular partition they will only be able to view the seismics that have been assigned to it.

Migrating¶

Register and retrieve a survey¶

Both the v0 and v1 endpoints can be used to create surveys. However, only the v1 endpoint will allow you to see the new seismic/seismic store objects.

As a rule of thumb, replacing survey with survey_v1 in API calls will likely be useful.

[1]:

# Setup
from cognite.seismic import CogniteSeismicClient

import os
import getpass

api_key = os.environ.get("COGNITE_API_KEY")
if api_key is None:
    api_key = getpass.getpass("Enter your Cognite API key: ")

client = CogniteSeismicClient(
    api_key=api_key,
    base_url="greenfield.cognitedata.com",
    project="public"
    )

[4]:

survey_name = "my_new_survey"
# v0
client.survey.register(survey_name)
client.survey.get(survey_name=survey_name)

#v1
client.survey.register(survey_name)
client.survey.get(
    survey_name=survey_name,
    # Can set these to True or False depending on requirements
    list_seismics=True,
    list_seismic_stores=True
)

[4]:

Survey {
id = 4e727d36-3608-4bc6-867c-93caf410b79b
external_id = None
name = my_new_survey
seismic_ids = []
seismic_store_ids = []
metadata = {}
coverage = None
}

Files¶

Files represent an object in a Cloud Storage containing a SEG-Y rev1 data stream. Usable as a source of data for ingestion. All query operations go via seismic objects. The process of registering, ingesting, or deleting files has not otherwise changed.

[ ]:

## Use file_seismic instead of file for all operations.
# v0
client.file.get(file_id="myFileId")
# v1
client.file_seismic.get(file_id="myFileId")

You can no longer request file coverage, nor can you query files for seismic data. This functionality has been moved to seismic objects. Please reference the v1 api overview for full information on querying traces.

[2]:

## Coverage
# v0
# client.file.get_file_coverage(file_id="myFileId")
# v1
"Let's look up the seismic store id corresponding to the file."
store_id = -1
for store in client.seismicstore.list(include_file_info=True):
    if store.ingested_file.id == "51fee0ef-fe31-403e-b910-62f3164a6bbe":
        store_id = store.id
        break
if store_id != -1:
    store = client.seismicstore.get(id=store_id)
else:
    print("Could not find seismic store with that file id!")

It’s also possible to more easily query a file by creating a new Seismic object, as detailed in the v1 api overview, with a view equal to the entire seismic store. You can assign an external id to the newly created Seismic that corresponds to the file ID. However, we may introduce external ids for Seismic Stores in the future, and/or automatically create whole-file Seismics with an appropriate external id.

Once you have the seismic store ID that corresponds to the file you wish to query, you can run any of the v1 API endpoints with that ID. Unlike the v0 API, most metadata is retrieved with one API call.

[4]:

# Using the 'store' variable from above...
## Headers
store.text_header
store.binary_header
## Ingested file
store.ingested_file
## Line ranges
print(store.inline_volume_def.get_inline_range())
print(store.inline_volume_def.get_xline_range())

{1: (20, 24), 2: (20, 24), 4: (20, 24), 3: (20, 24), 5: (20, 24)}
{20: (1, 5), 21: (1, 5), 22: (1, 5), 23: (1, 5), 24: (1, 5)}

Querying¶

Other than the file->seismic(store) change, the major change in querying seismic data in the v1 API is that the specialized methods (slice by inline, slice by crossline, cube…) have been replaced with a single, generalized get_volume method.

[ ]:

# Getting an inline
client.volume.get_volume(
    seismic_store_id=store.id,
    inline_range=[0, 100]
)
# Getting an inline with a step size of 3
client.volume.get_volume(
    seismic_store_id=store.id,
    inline_range=[0, 100, 3]
)
# Getting a crossline
client.volume.get_volume(
    seismic_store_id=store.id,
    xline_range=[0, 100]
)
# Currently we do not have a replacement for slice by arbitrary lines or geometry, but it is planned.

# Getting a time/depth slice
client.volume.get_volume(
    seismic_store_id=store.id,
    z_range=[0, 10]
)

# Getting an entire volume
client.volume.get_volume(seismic_store_id=store.id)

# Getting a cube
client.volume.get_volume(
    seismic_store_id=store.id,
    inline_range=[0, 100],
    xline_range=[0, 20, 3],
    z_range=[2, 5]
)

Deprecation¶

Some APIs have been deprecated or removed in the release on the v1 API.

File query APIs¶

Endpoints used to query file trace data, such as file.get_xlines_by_inline file.get_inlines_by_xline volume.get_cube_by_geometry time_slice.get_time_slice_by_lines time_slice.get_time_slice_by_geometry have been removed in favor of using the seismic store endpoint get_volume.

Endpoints used to grant file access, such as grant_access and revoke_access have been removed. The functionality is replaced by partitions and seismics.

Endpoints used to query file metadata, such as get_binary_header get_text_header get_file_coverage have been removed. APIs used to query seismic stores, such as get list search have arguments to fetch header or coverage data without having to make a separate call.