DLIS Metadata

Together with the actual logs, there is often an abundance of metadata related to the acquisition of the logs. In a DLIS-file metadata is structured into different dict-like objects that describe certain pieces of information. RP66v1 defines over 20 object-types. In practice, only a handful see widespread use. Please refer to the DLIS API Reference to get a full [1] overview of the different object-types. Here are some examples of the frequently used ones:

Origin: Contains general information about the file, and the circumstances in which it was produced.

Channel: Description of a specific curve in the logical file.

Frame: A grouping of channels that all share the same index, typically a logpass. The actual curve-data are accessed through Frames.

Tool: Describes a physical tool that was used for the acquisition of the logs.

Parameter: Contains some parameter value and a description of it.

[1]

There is currently a handful of object-types (mostly from Chaper 7: semantics: dictionaries of RP66v1) that dlisio does not implement full support for. I.e. they are not translated into their own python class, but rather use the more generic and rough interface of BasicObject. These rarely see the light of day, but if present they can be accessed through LogicalFile.unknowns.

Identifying specific objects

Common for all objects are the four fields: type, name (mnemonic), origin and copynumber. Together, these form a unique identifier for the object. RP66v1 states that no two objects from the same logical file can have the same value for all four fields.

origin: The origin field states which origin the object is a part of. Its interger value implicitly refers to the Origin-object that has the same value in its origin field.

copynumber: The copynumber is used to distinguish two objects that otherwise have an identical signature. E.g. if there are two Channel objects with the same name/mnemonic and both belong to the same origin.

To access a specific object use LogicalFile.object(). Or search for objects matching a regular expression with LogicalFile.find()

>>> channel = f.object('CHANNEL', 'GR', origin=1, copynumber=0)
>>> channel.long_name
'Gamma Ray'

>>> f.find('CHANNEL', '.*GR.*')
[Channel(GR), Channel(RGR)]

Note

Note that LogicalFile.object() allows you to ommit the origin and/or copynumber, but will raise if it’s unable to uniquely identify the object. The documentation for LogicalFile.object() and LogicalFile.find() offers more examples.

Relationship between metadata objects

A key feature of RP66v1 is that objects refer to each other. Object-to-object referencing is used to establish a relationship between two objects. This relationship can serve as an implicit context to the object. Many objects rely on this context and make little sense without it.

Object-references are conveyed through the object’s attributes. A concrete example is Tool.channels, which references all the channels that are produced directly by that tool. dlisio automatically resolves object references to make it easy to work with programmatically:

>>> tool = f.object('TOOL', 'USIT')
>>> tool.channels
[TDEP, BI, CBL, CBLF, CBSL, ..., CMCG, WF1, WF1N, WF2, WF2N]

>>> channel = tool.channels[1]
>>> channel.long_name
'Bond Index'

Units

Alongside attribute values, a DLIS-file also contains a corresponding units field. This is true for all object attributes, even when units make little sense, such as for Channel.long_name.

Currently there is no nice interface for accessing units with dlisio. They are, however, reachable through some of the more basic interfaces. Sensible units are also printed in BasicObject.describe().

Each metadata object has in itself an attribute attic, BasicObject.attic. The attic is a complete dict-like representation of the object, but without the syntactic sugar provided by the specialized class of the object.

At the moment attribute units are only accessible through the attic: obj.attic['ATTRIBUTE'].units.

Every attribute has a RP66V1 name section in its docs that corresponds to the ATTRIBUTE value, which must be used to retrieve the raw attribute.

For example, given the object frame and docs for Frame.spacing:

>>> frame.spacing
... 800
>>> frame.attic['SPACING'].units
... '0.5 ms'

Multiple origins

RP66v1 allows for a single logical file to have multiple Origin-objects. Origin describes the source of the data, such as which field and well it’s from. It’s therefore theoretically possible that the data contained in a logical file stem from different sources when there are more than one Origin-objects. Such files obviously need special care. More precisely, the origin field of each object that is accessed needs to be examined in order to determine which origin it belongs to.

The majority of files do not contain multiple origins, which makes it safe to ignore the origin field. However, it is considered a good practice to check the origin count when opening a new file, e.g. by issuing a warning if there are more than one:

import logging
from dlisio import dlis

with dlis.load(path) as (f, *tail):
   if len(f.origins) > 1: logging.warning('File contains multiple origins')

Vendor-specific metadata

In addition to the many object-structures defined by RP66v1 itself, vendors are free to specify their own metadata objects. However, with often cryptic naming and minimal explanation, such objects can be challenging to decipher without any external explanation of the intent of these objects.

The vendor-specific objects are reachable through f.unknowns:

with dlis.load(path) as (f, *tail):
   f.unknowns