dliswriter

https://github.com/well-id/dliswriter
Admin
dliswriter is an open-source Python package for creating and writing DLIS (Digital Log Interchange...
Tokens:16,542
Snippets:150
Trust Score:4.2
License:MIT
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Clone and enter the dliswriter repository

Source: https://github.com/well-id/dliswriter/blob/master/README.md

Clone the dliswriter repository from GitHub and change into the cloned directory. This is the first step in the development setup.

```commandline
git clone https://github.com/well-id/dliswriter.git
cd dliswriter
```

--------------------------------

### Install dliswriter via conda

Source: https://github.com/well-id/dliswriter/blob/master/README.md

Use this command to install dliswriter from the conda-forge channel. Ensure you are in a conda environment before running it.

```commandline
conda install dliswriter -c conda-forge
```

--------------------------------

### Install dliswriter via pip

Source: https://github.com/well-id/dliswriter/blob/master/README.md

Use this command to install the latest release of dliswriter from PyPI. Run it in your terminal or command prompt.

```commandline
pip install dliswriter
```

--------------------------------

### Create a DLIS file with channels and a frame

Source: https://github.com/well-id/dliswriter/blob/master/README.md

Minimal example of using dliswriter to create a DLIS file. It creates a DLISFile, adds a logical file with an origin, defines three channels with mock data, adds a frame referencing those channels, and writes the file to disk. Requires numpy and the dliswriter package.

```python
import numpy as np  # for creating mock datasets
from dliswriter import DLISFile, enums

df = DLISFile()

lf = df.add_logical_file()  # a DLIS file is basically comprised of independent fully self-contained logical files

lf.add_origin("MY-ORIGIN")  # required; can contain metadata about the well, scan procedure, etc.

# define channels with numerical data and additional information
n_rows = 100  # all datasets must have the same number of rows
ch1 = lf.add_channel('DEPTH', data=np.linspace(0, 10, n_rows), units=enums.Unit.METER)
ch2 = lf.add_channel("RPM", data=np.arange(n_rows) % 10)
ch3 = lf.add_channel("AMPLITUDE", data=np.random.rand(n_rows, 5))

# define frame, referencing the above defined channels
main_frame = lf.add_frame("MAIN-FRAME", channels=(ch1, ch2, ch3), index_type=enums.FrameIndexType.BOREHOLE_DEPTH)

# write the data and metadata to a physical DLIS file
df.write('./new_dlis.DLIS')
```

--------------------------------

### Run dliswriter tests with pytest

Source: https://github.com/well-id/dliswriter/blob/master/README.md

Run the package's test suite using pytest. Execute this from the dliswriter directory to verify the development setup.

```commandline
pytest .
```

--------------------------------

### Install dliswriter in editable mode

Source: https://github.com/well-id/dliswriter/blob/master/README.md

Install dliswriter in editable mode with pip, disabling build isolation and dependencies. This links the source code to the environment for development.

```commandline
pip install --no-build-isolation --no-deps -e .
```

--------------------------------

### Create DLIS file with lowercase channel name in high-compatibility mode

Source: https://github.com/well-id/dliswriter/blob/master/docs/userguide/compatibilityissues.rst

Example of creating a DLIS file with a channel named 'Depth' inside high-compatibility mode. This will raise a ValueError because the name contains lowercase characters.

```python
with high_compatibility_mode:
    df = DLISFile()
    lf = df.add_logical_file()
    lf.add_origin("MY-ORIGIN")
    ch1 = lf.add_channel('Depth', data=np.arange(100) / 10, units=Renums.Unit.METER)
```

--------------------------------

### Create DLISFile with custom SUL, File Header, and Origin

Source: https://github.com/well-id/dliswriter/blob/master/docs/userguide/extendingmetadata.rst

Shows how to create a DLISFile with custom Storage Unit Label and File Header parameters, add a logical file, and add an Origin with detailed metadata. The add_origin method accepts keyword arguments for file set name, file set number, file number, well ID, and well name.

```python
from dlis_writer.file import DLISFile

# define DLISFile passing more information for creating Storage Unit Label and File Header
df = DLISFile(
  set_identifier="MY-SET",
  sul_sequence_number=5,
  max_record_length=4096,
)

first_logical_file = df.add_logical_file(
  fh_id=in_fheaderid_truncated,
  fh_sequence_number=int(in_fheader.sequencenr),
  fh_identifier=str(int(in_fheader.name)),
)

# add Origin with more details
# see more available keyword arguments in DLISFile.add_origin()
origin = first_logical_file.add_origin(
  'MY-ORIGIN',
  file_set_name='MY-FILE-SET-NAME',
  file_set_number=11,
  file_number=22,
  well_id="55",
  well_name='MY-WELL'
)
```

--------------------------------

### Activate high-compatibility mode with context manager

Source: https://github.com/well-id/dliswriter/blob/master/docs/userguide/compatibilityissues.rst

Activates the high-compatibility mode using the dedicated context manager. In this mode, the writer raises errors when potential viewer issues are detected.

```python
from dlis_writer import high_compatibility_mode

with high_compatibility_mode:
    # your code goes here
```

--------------------------------

### Add frame and computation with references

Source: https://github.com/well-id/dliswriter/blob/master/docs/developerguide/writingfile/dlisfileobject.rst

Shows how to mark relations by passing lower-level objects (channel, axis) as arguments when creating higher-level objects. A frame can have multiple channels, while a computation can only have one axis.

```python
a_frame = logical_file.add_frame(..., channels=(a_channel, ...))   # frame can have multiple channels
a_computation = logical_file.add_computation(..., axis=an_axis)    # computation can only have 1 axis
```

--------------------------------

### Create DLISFile and add logical file, channel, axis

Source: https://github.com/well-id/dliswriter/blob/master/docs/developerguide/writingfile/dlisfileobject.rst

Creates a DLISFile and adds a logical file, then adds a channel and an axis. This is the only place where the h5py-style add method is available; all other objects must be added through a logical file.

```python
dlis_file = DLISFile()
logical_file = dlis_file.add_logical_file()  # a DLIS file is basically comprised of independent fully self-contained logical files
a_channel = logical_file.add_channel(...)
an_axis = logical_file.add_axis(...)
```

--------------------------------

### Pass Units with Value Using a Dictionary

Source: https://github.com/well-id/dliswriter/blob/master/docs/userguide/addingmoreobjects.rst

Shows an alternative way to specify zone minimum and maximum values by passing a dictionary with 'value' and 'units' keys. Useful for combining value and unit in a single argument.

```python
zone3 = df.add_zone('VDEPTH-ZONE', domain=enums.ZoneDomain.VERTICAL_DEPTH,
                    minimum={'value': 10, 'units': enums.Unit.METER},
                    maximum={'value': 30, 'units': 'm'})
```

--------------------------------

### h5py-style add_dataset call

Source: https://github.com/well-id/dliswriter/blob/master/docs/developerguide/writingfile/dlisfileobject.rst

Shows the h5py-style API that inspired the DLISFile interface, where a child object is created and linked to a parent in one call. This pattern is only available from the top-level DLISFile in dlis-writer.

```python
new_h5_dataset = some_h5_group.add_dataset(...)
```

--------------------------------

### Create a minimal DLIS file with dlis_writer

Source: https://github.com/well-id/dliswriter/blob/master/docs/userguide/minimalexample.rst

Use this snippet to create a minimal DLIS file with two 1D channels (one serving as the index) and a single 2D channel. It initializes a DLISFile object, adds an origin, defines channels with mock data, creates a frame with BOREHOLE_DEPTH index type, and writes the file to './new_dlis_file.DLIS'. All datasets in the same frame must have the same number of rows.

```python
import numpy as np  # for creating mock datasets
from dlis_writer import DLISFile, enums

# create a DLISFile object
# this also initialises Storage Unit Label and File Header with minimal default information
df = DLISFile()

# add Origin
df.add_origin("MY-ORIGIN")

# number of rows for creating the datasets
# all datasets (channels) belonging to the same frame must have the same number of rows
n_rows = 100

# define channels with numerical data and additional information
#  1) the first channel is also the index channel of the frame;
#     must be 1D, ideally should be monotonic and equally spaced
ch1 = df.add_channel('DEPTH', data=np.arange(n_rows) / 10, units=enums.Unit.METER)

#  2) second channel; in this case 1D and unitless
ch2 = df.add_channel("RPM", data=(np.arange(n_rows) % 10).astype(float))

#  3) third channel - an image channel (2D data)
ch3 = df.add_channel("AMPLITUDE", data=np.random.rand(n_rows, 5))

# define frame, referencing the above defined channels
main_frame = df.add_frame("MAIN-FRAME", channels=(ch1, ch2, ch3), index_type=enums.FrameIndexType.BOREHOLE_DEPTH)

# when all the required objects have been added, write the data and metadata to a physical DLIS file
df.write('./new_dlis_file.DLIS')
```

--------------------------------

### Create and activate the dlis-writer conda environment

Source: https://github.com/well-id/dliswriter/blob/master/README.md

Create a conda environment named 'dlis-writer' from the environment.yaml file and activate it. This environment contains the dependencies needed for development.

```commandline
conda env create -f environment.yaml
conda activate dlis-writer
```

--------------------------------

### Set Units on Zone Attributes

Source: https://github.com/well-id/dliswriter/blob/master/docs/userguide/addingmoreobjects.rst

Illustrates setting units for zone minimum and maximum values via the `.units` attribute. Units can be specified using `enums.Unit` enums or simple strings like 's' for seconds. Simple strings are also accepted.

```python
zone1.minimum.units = enums.Unit.INCH  # inches
zone2.maximum.units = 's'   # seconds; simple strings are also accepted
```

--------------------------------

### Add Zone Objects with Domain and Range

Source: https://github.com/well-id/dliswriter/blob/master/docs/userguide/addingmoreobjects.rst

Shows how to add Zone objects to the DLIS file using `df.add_zone()`. Each zone specifies a domain (depth or time) and minimum/maximum values. Zones can be created for borehole depth, time, or vertical depth.

```python
zone1 = df.add_zone('DEPTH-ZONE', domain=enums.ZoneDomain.BOREHOLE_DEPTH, minimum=2, maximum=4.5)
zone2 = df.add_zone('TIME-ZONE', domain=enums.ZoneDomain.TIME, minimum=10, maximum=30)
```

--------------------------------

### Add Splice Object Referencing Channels and Zones

Source: https://github.com/well-id/dliswriter/blob/master/docs/userguide/addingmoreobjects.rst

Demonstrates adding a Splice object using `df.add_splice()` with `input_channels`, `output_channel`, and `zones` arguments. Shows how Zone objects can be used to define Splice objects, referencing previously added channels.

```python
splice1 = df.add_splice('SPLICE1', input_channels=(ch1, ch2), output_channel=ch3, zones=(zone1, zone2))
```

--------------------------------

### Reuse axis for parameter and channel

Source: https://github.com/well-id/dliswriter/blob/master/docs/developerguide/writingfile/dlisfileobject.rst

Demonstrates reusing an already defined axis object for multiple higher-level objects. Both Parameter and Channel can accept multiple axes.

```python
# (multiple axes possible for both Parameter and Channel)
a_param = logical_file.add_parameter(..., axis=(an_axis, ...))
another_channel = logical_file.add_channel(..., axis=(an_axis, ...))
```

--------------------------------

### Change Origin attribute value

Source: https://github.com/well-id/dliswriter/blob/master/docs/userguide/extendingmetadata.rst

Shows how to change an attribute of an Origin object after creation. Because most attributes are instances of the Attribute class, you must use the .value (or .unit) property to modify the value.

```python
origin.company.value = "COMPANY X"
```
Tokens:
Raw