[](./LICENSE)
[](https://github.com/well-id/dliswriter/actions/workflows/Pytest.yml)
[](https://github.com/well-id/dliswriter/actions/workflows/mypy.yml)
[](https://github.com/well-id/dliswriter/actions/workflows/Flake8.yml)
[](https://well-id-widcdliswriter.readthedocs-hosted.com/?badge=latest)
# `dliswriter`
<p align="center" width="100%">
<img width="15%" src="https://github.com/well-id/dliswriter/raw/master/src/dliswriter/logo.png">
</p>
Welcome to `dliswriter` - an open-source Python package for writing DLIS files.
The package allows you to specify the structure, data, and metadata of your DLIS file
in a simple and flexible fashion. A minimal example is shown below.
```python
import numpy as np # for creating mock datasets
from dliswriter import DLISFile, enums
df = DLISFile()
df.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 = df.add_channel('DEPTH', data=np.linspace(0, 10, n_rows), units=enums.Unit.METER)
ch2 = df.add_channel("RPM", data=np.arange(n_rows) % 10)
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)
# write the data and metadata to a physical DLIS file
df.write('./new_dlis_file.DLIS')
```
For more details about the DLIS file format and using `dliswriter`, please see [the documentation](https://well-id-widcdliswriter.readthedocs-hosted.com/index.html).
### Performance
According to our rough measurements, the file writing time seems to be pretty much linearly dependent on the
amount of data, in particular the number of rows. There is also some dependency on the dimensionality
of the data - e.g a single image (2D dataset) with 1000 columns will write about 20% faster
than 10 images of 100 columns each. A rough estimate of the writing speed is about 20M `float64` values per second
(measured on an x64-based PC with Intel Core i9-8950HK with MS Windows 11 and Python 3.9.19).
The performance may be further tuned by adjusting the `input_chunk_size` and `output_chunk_size` of the writer
(see [this example](./examples/create_synth_dlis_variable_data.py)). The former limits how much of the input
data are loaded to memory at a time; the latter denotes the number of output bytes kept in memory before each partial
file write action. The optimal values depend on the hardware/software configuration and the characteristics of the data
(number and dimensionality of the datasets), but the defaults should in general be a good starting point.
### Compatibility notes
Please note that some DLIS viewer applications are not fully compliant with the DLIS standard.
If a DLIS file produced by `dliswriter` causes issues in some of the viewers, it might not necessarily
be a `dliswriter` bug.
Some of the known compatibility issues - and ways of dealing with them - are described
[in a dedicated section of the documentation](https://well-id-widcdliswriter.readthedocs-hosted.com/userguide/compatibilityissues.html).
If you run into problems not covered by the documentation, please open a new [issue](https://github.com/well-id/dliswriter/issues).
## Installation
`dliswriter` can be installed from PyPI:
```commandline
pip install dliswriter
```
Anaconda installation option is coming soon.
### For developers
Setting up `dliswriter` for development purposes requires:
- Python (at least 3.9)
- Anaconda, e.g. [Miniconda](https://docs.anaconda.com/free/miniconda/)
- [git](https://git-scm.com/)
Once these requirements are fulfilled, follow the steps below:
1. Clone the repository and enter it. From a console:
```commandline
git clone https://github.com/well-id/dliswriter.git
cd dliswriter
```
2. Create the `dlis-writer` environment from the [`environment.yaml`](./environment.yaml) file and activate it:
```commandline
conda env create -f environment.yaml
conda activate dlis-writer
```
4. Install DLIS Writer in editable mode using `pip`:
```commandline
pip install --no-build-isolation --no-deps -e .
```
For explanation of the required flags, see [this issue](https://github.com/conda/conda-build/issues/4251).
5. You're good to go! For verification, you can run the tests for the package
(still from inside the `dliswriter` directory):
```commandline
pytest .
```
## Contributing
To contribute to the `dliswriter`, please follow this procedure:
1. Fork the repository
2. Clone the fork to your computer
3. Check out the `devel` branch: `git checkout devel`
4. Create a new branch from `devel`: `git checkout -b <your branch name>`
5. Make your changes, commit them, and push them
6. From the GitHub page of your fork, create a pull request to the original repository.
You can find some more detailed instructions about the fork-and-pull request workflow
[in the GitHub Docs](https://docs.github.com/en/get-started/exploring-projects-on-github/contributing-to-a-project).
You might also want to have a look at our [issues log](https://github.com/well-id/dliswriter/issues).
---
## Authors
`dliswriter` has been developed at [Well ID](https://wellid.no/) by:
* Dominika Dlugosz
* Magne Lauritzen
* Kamil Grunwald
* Omer Faruk Sari
Based on the definition of the [RP66 v1 standard](https://energistics.org/sites/default/files/RP66/V1/Toc/main.html).
Raw data
{
"_id": null,
"home_page": null,
"name": "dliswriter",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "Dominika Dlugosz <dominika.dlugosz@wellid.no>",
"keywords": "RP66, RP66 v1, binary file IO, data, dlis, dlisio, drilling, oil and gas, petroleum engineering, well imaging, well logging",
"author": "Omer Faruk Sari",
"author_email": "Dominika Dlugosz <dominika.dlugosz@wellid.no>, Magne Lauritzen <magne.lauritzen@wellid.no>, Kamil Grunwald <kamil.grunwald@wellid.no>",
"download_url": "https://files.pythonhosted.org/packages/55/57/35e3ff5f00ff64284e2b7daea0e3f7159fa14756fc29a686fdc823779954/dliswriter-1.0.1.tar.gz",
"platform": null,
"description": "[](./LICENSE)\n\n[](https://github.com/well-id/dliswriter/actions/workflows/Pytest.yml)\n[](https://github.com/well-id/dliswriter/actions/workflows/mypy.yml)\n[](https://github.com/well-id/dliswriter/actions/workflows/Flake8.yml)\n[](https://well-id-widcdliswriter.readthedocs-hosted.com/?badge=latest)\n\n\n# `dliswriter`\n\n<p align=\"center\" width=\"100%\">\n <img width=\"15%\" src=\"https://github.com/well-id/dliswriter/raw/master/src/dliswriter/logo.png\">\n</p>\n\n\nWelcome to `dliswriter` - an open-source Python package for writing DLIS files.\n\nThe package allows you to specify the structure, data, and metadata of your DLIS file\nin a simple and flexible fashion. A minimal example is shown below.\n\n```python\nimport numpy as np # for creating mock datasets\nfrom dliswriter import DLISFile, enums\n\ndf = DLISFile()\n\ndf.add_origin(\"MY-ORIGIN\") # required; can contain metadata about the well, scan procedure, etc.\n\n# define channels with numerical data and additional information\nn_rows = 100 # all datasets must have the same number of rows\nch1 = df.add_channel('DEPTH', data=np.linspace(0, 10, n_rows), units=enums.Unit.METER)\nch2 = df.add_channel(\"RPM\", data=np.arange(n_rows) % 10)\nch3 = df.add_channel(\"AMPLITUDE\", data=np.random.rand(n_rows, 5))\n\n# define frame, referencing the above defined channels\nmain_frame = df.add_frame(\"MAIN-FRAME\", channels=(ch1, ch2, ch3), index_type=enums.FrameIndexType.BOREHOLE_DEPTH)\n\n# write the data and metadata to a physical DLIS file\ndf.write('./new_dlis_file.DLIS')\n```\n\nFor more details about the DLIS file format and using `dliswriter`, please see [the documentation](https://well-id-widcdliswriter.readthedocs-hosted.com/index.html).\n\n### Performance\nAccording to our rough measurements, the file writing time seems to be pretty much linearly dependent on the \namount of data, in particular the number of rows. There is also some dependency on the dimensionality \nof the data - e.g a single image (2D dataset) with 1000 columns will write about 20% faster \nthan 10 images of 100 columns each. A rough estimate of the writing speed is about 20M `float64` values per second\n(measured on an x64-based PC with Intel Core i9-8950HK with MS Windows 11 and Python 3.9.19).\n\nThe performance may be further tuned by adjusting the `input_chunk_size` and `output_chunk_size` of the writer\n(see [this example](./examples/create_synth_dlis_variable_data.py)). The former limits how much of the input \ndata are loaded to memory at a time; the latter denotes the number of output bytes kept in memory before each partial \nfile write action. The optimal values depend on the hardware/software configuration and the characteristics of the data\n(number and dimensionality of the datasets), but the defaults should in general be a good starting point.\n\n\n### Compatibility notes\n\nPlease note that some DLIS viewer applications are not fully compliant with the DLIS standard.\nIf a DLIS file produced by `dliswriter` causes issues in some of the viewers, it might not necessarily \nbe a `dliswriter` bug.\nSome of the known compatibility issues - and ways of dealing with them - are described \n[in a dedicated section of the documentation](https://well-id-widcdliswriter.readthedocs-hosted.com/userguide/compatibilityissues.html).\nIf you run into problems not covered by the documentation, please open a new [issue](https://github.com/well-id/dliswriter/issues).\n\n\n## Installation\n`dliswriter` can be installed from PyPI:\n\n```commandline\npip install dliswriter\n```\n\nAnaconda installation option is coming soon.\n\n### For developers\nSetting up `dliswriter` for development purposes requires: \n- Python (at least 3.9)\n- Anaconda, e.g. [Miniconda](https://docs.anaconda.com/free/miniconda/)\n- [git](https://git-scm.com/)\n\nOnce these requirements are fulfilled, follow the steps below:\n\n1. Clone the repository and enter it. From a console:\n ```commandline\n git clone https://github.com/well-id/dliswriter.git\n cd dliswriter\n ```\n\n2. Create the `dlis-writer` environment from the [`environment.yaml`](./environment.yaml) file and activate it:\n ```commandline\n conda env create -f environment.yaml\n conda activate dlis-writer\n ```\n\n4. Install DLIS Writer in editable mode using `pip`:\n ```commandline\n pip install --no-build-isolation --no-deps -e .\n ```\n For explanation of the required flags, see [this issue](https://github.com/conda/conda-build/issues/4251).\n\n5. You're good to go! For verification, you can run the tests for the package \n(still from inside the `dliswriter` directory):\n ```commandline\n pytest .\n ```\n\n## Contributing\nTo contribute to the `dliswriter`, please follow this procedure:\n1. Fork the repository\n2. Clone the fork to your computer\n3. Check out the `devel` branch: `git checkout devel`\n4. Create a new branch from `devel`: `git checkout -b <your branch name>`\n5. Make your changes, commit them, and push them \n6. From the GitHub page of your fork, create a pull request to the original repository.\n\nYou can find some more detailed instructions about the fork-and-pull request workflow \n[in the GitHub Docs](https://docs.github.com/en/get-started/exploring-projects-on-github/contributing-to-a-project).\n\nYou might also want to have a look at our [issues log](https://github.com/well-id/dliswriter/issues).\n\n---\n## Authors\n`dliswriter` has been developed at [Well ID](https://wellid.no/) by:\n\n* Dominika Dlugosz\n* Magne Lauritzen\n* Kamil Grunwald\n* Omer Faruk Sari\n\nBased on the definition of the [RP66 v1 standard](https://energistics.org/sites/default/files/RP66/V1/Toc/main.html).\n",
"bugtrack_url": null,
"license": null,
"summary": "An open-source Python package for writing DLIS files.",
"version": "1.0.1",
"project_urls": {
"Changelog": "https://well-id-widcdliswriter.readthedocs-hosted.com/changelog.html",
"Documentation": "https://well-id-widcdliswriter.readthedocs-hosted.com/",
"Homepage": "https://github.com/well-id/dliswriter",
"Issues": "https://github.com/well-id/dliswriter/issues"
},
"split_keywords": [
"rp66",
" rp66 v1",
" binary file io",
" data",
" dlis",
" dlisio",
" drilling",
" oil and gas",
" petroleum engineering",
" well imaging",
" well logging"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "fbbed8c112008eb2d5185b06b8c60cc3f1e59634f70529ae0e45b0684d061e90",
"md5": "475ef8871827cf25f65c59022ff8a389",
"sha256": "ab36d7df5b771b1416f525362325247d602dc53bdcb6ab5c74f1ec64063972d4"
},
"downloads": -1,
"filename": "dliswriter-1.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "475ef8871827cf25f65c59022ff8a389",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 120837,
"upload_time": "2024-04-25T08:18:21",
"upload_time_iso_8601": "2024-04-25T08:18:21.346968Z",
"url": "https://files.pythonhosted.org/packages/fb/be/d8c112008eb2d5185b06b8c60cc3f1e59634f70529ae0e45b0684d061e90/dliswriter-1.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "555735e3ff5f00ff64284e2b7daea0e3f7159fa14756fc29a686fdc823779954",
"md5": "832177a536b081086ae70ac997dfe5e4",
"sha256": "1ba0f4486bd5f08894c0f74b8164e8070bae34c496b30a6f5638aa5f46eb7c53"
},
"downloads": -1,
"filename": "dliswriter-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "832177a536b081086ae70ac997dfe5e4",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 158909,
"upload_time": "2024-04-25T08:18:23",
"upload_time_iso_8601": "2024-04-25T08:18:23.356091Z",
"url": "https://files.pythonhosted.org/packages/55/57/35e3ff5f00ff64284e2b7daea0e3f7159fa14756fc29a686fdc823779954/dliswriter-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-25 08:18:23",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "well-id",
"github_project": "dliswriter",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "dliswriter"
}
JSON
