Merge branch 'Dominika_feature_about-to-publish'

README.md

@@ -1,74 +1,98 @@
-# `widc.dliswriter`
+# `dliswriter`
 
-This is a repository containing the DLIS Writer - a Python package for creating DLIS files.
+Welcome to `dliswriter` - an open-source Python package for writing DLIS files.
 
-For more details, please see [the documentation](https://well-id-widcdliswriter.readthedocs-hosted.com/en/latest/).
-
-## Installation instructions
-`widc.dliswriter` can be installed just like other WellID packages.
-
-From a console:
-
-```commandline
-pip install git+https://%GIT_PAT%:x-oauth-basic@github.com/well-id/widc.dliswriter@master
-```
-
-From requirements.txt:
-
-```commandline
-git+https://${GIT_PAT}:x-oauth-basic@github.com/well-id/widc.dliswriter@master
-```
-
-## Using `widc.dliswriter`
-When using the DLIS Writer, the main class you interact with is `DLISFIle`.
-An instance of this class allows you to define the structure of your DLIS and specify the data it should contain.
-
-A minimal example is shown below:
+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 dlis_writer.file import DLISFile  # the main dlis-writer object you will interact with
+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.arange(n_rows) / 10, units='m')
-ch2 = df.add_channel("RPM", data=(np.arange(n_rows) % 10).astype(float))
+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='BOREHOLE-DEPTH')
+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')
 ```
 
-Note that some DLIS viewers additionally restrict the expected format of the DLIS files.
-In other words, if a DLIS file produced by the DLIS Writer causes issues in some of the viewers,
-it might not necessarily be a DLIS Writer bug.
+For more details about the DLIS file format and using `dliswriter`, please see [the documentation](https://well-id-widcdliswriter.readthedocs-hosted.com/index.html).
+
+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 the documentation](https://well-id-widcdliswriter.readthedocs-hosted.com/en/latest/userguide/compatibilityissues.html).
+[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).
 
 
-## Contributing to `widc.dliswriter`
-To contribute to `widc.dliswriter`, please first read the 
-[Contributing](https://well-id-well-id-software-documentation.readthedocs-hosted.com/en/latest/for_developers/contribute.html) 
-section of Well ID's software documentation. In short, follow these steps:
+## Installation
+`dliswriter` can be installed from PyPI:
 
-* Clone the repository to your machine: `git clone https://github.com/well-id/widc.dliswriter.git`
-* Checkout the `devel` branch: `git checkout devel`
-* Create a new branch: `git checkout -b <your branch name>`
-* Make your changes, commit them, and push them.
-* Create a pull request to the `devel` branch.
+```commandline
+pip install dliswriter
+```
 
+Anaconda installation option is coming soon.
+
+### For developers
+Setting up `dliswriter` for development purposes requires: 
+- Python (at least 3.10)
+- 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. Check out the `devel` branch: `git checkout devel`
+2. Create a new branch from `devel`: `git checkout -b <your branch name>`
+3. Make your changes, commit them, and push them
+4.  Create a pull request to the `devel` branch
+
+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
 
-With inputs from Magne Lauritzen.
-
 Based on the definition of the [RP66 v1 standard](https://energistics.org/sites/default/files/RP66/V1/Toc/main.html).

docs/conf.py

@@ -8,7 +8,7 @@
 
 project = 'DLIS Writer'
 copyright = '2023, Well ID'
-author = 'Dominika Dlugosz, Kamil Grunwald, Omer Faruk Sari'
+author = 'Dominika Dlugosz, Magne Lauritzen, Kamil Grunwald, Omer Faruk Sari'
 release = '0.0.10'
 
 # -- General configuration ---------------------------------------------------
@@ -32,7 +32,7 @@
 html_context = {
     "display_github": True,
     "github_user": "well-id",
-    "github_repo": "dlis-writer",
+    "github_repo": "dliswriter",
     "github_version": "main",
     "conf_py_path": "/docs/",
 }

environment.yaml

@@ -3,18 +3,17 @@ channels:
   - conda-forge
   - defaults
 dependencies:
-  - python>=3.10
+  - python>=3.9
   - flake8
   - mypy
   - pytest
-  - numpy
+  - numpy>=1.19.2  # 1.16.6 does not work; 1.19.2 seems to be the next installable version for Python 3.9 (conda-forge)
   - h5py
   - progressbar2
-  - coloredlogs
-  - typing_extensions
+  - typing_extensions>=4.0.1  # patch to 'Fix usage of Self as a type argument' (from release notes)
+  - coloredlogs    # used only in examples
+  - hatchling      # build - needed to install dliswriter in editable mode using pip
+  - editables      # build (see above)
   - pip
-  - pandas  # for reading data from csv and xls(x) files, only used in file_format_formatter subpackage
-  - pytz
   - pip:
-      - dlisio
-      - lasio   # for reading data from LAS files, only used in file_format_formatter subpackage
+      - dlisio>=1.0.1

examples/README.md

@@ -9,10 +9,5 @@ It is also shown how multiple frames (in this case, a depth-based and a time-bas
 - [create_dlis_equivalent_frames.py](./examples/create_dlis_from_data.py) shows how to make a DLIS file containing multiple frames of the same 
 structure (the same set of channel names etc.).
 
-- [create_dlis_from_data.py](./examples/create_dlis_from_data.py) can be used to make a DLIS file
-from a hdf5, csv, las, and xlx/xlsx data source.
-
 - [create_synth_dlis_variable_data.py](./examples/create_synth_dlis_variable_data.py) allows creating DLIS files
 with any number of 2D datasets with a user-defined shape, filled with randomised data. 
-
-

examples/create_dlis_equivalent_frames.py

@@ -10,12 +10,13 @@
 import numpy as np
 import logging
 
-from dlis_writer import DLISFile, EFLRItem, enums, eflr_types
-from dlis_writer.utils.logging import install_colored_logger
+from dliswriter import DLISFile, EFLRItem, enums, eflr_types
+
+from utils import install_colored_logger
 
 
 # colored logs output
-install_colored_logger(logging.getLogger('dlis_writer'))
+install_colored_logger(logging.getLogger('dliswriter'))
 
 
 # create DLISFile instance; optionally, pass arguments for creating file header & storage unit label

examples/create_synth_dlis.py

@@ -4,12 +4,13 @@
 import numpy as np
 import logging
 
-from dlis_writer.utils.logging import install_colored_logger
-from dlis_writer import AttrSetup, DLISFile, enums
+from dliswriter import AttrSetup, DLISFile, enums
+
+from utils import install_colored_logger
 
 
 # colored logs output
-install_colored_logger(logging.getLogger('dlis_writer'))
+install_colored_logger(logging.getLogger('dliswriter'))
 
 
 # create DLISFile instance; optionally, pass custom parameters for file header and storage unit label