deviation2welltrajectory 0.0.12
script to convert deviation survey into WELL_TRAJECTORY keyword for ECHELON simulator or WELTRAJ keyword for OPM flow.
Requires Python: >=3.10

# deviation2welltrajectory  
  
A script to help converting deviation surveys exported from Petrel (Schlumber) to include files apropriate for ECHELON (Stone Ridge Technology) using the ECHELON keyword WELL_TRAJECTORY, or for OPM flow using WELTRAJ keyword.
   
## How to use:  
### from the command line or terminal  
run the python command:  
`python -m deviation2welltrajectory input_path [output_filepath] [-e [extension]] [-r [recursive]] [-m [md_col]] [-x [x_col]] [-y [y_col]] [-z [z_col]] [-i [negate_x]] [-j [negate_y]] [-k [negate_z]] [-u [output_units]]`  

where `input_path` can be:  
- the path to the deviation survey file to be converted  
- a folder containing the deviation files - all the files will be converted -  
- a pattern representing the files to be processed  
   
The rest of the parameters are described under the [Parameters](#Parameters) section.  
  
### from Python  
`import deviation2welltrajectory as d2wt`  
`d2wt.convert( input filepath, [output path] )`  
  
## Parameters  
Only the fist parameter, `input_filepath`, indicative of the input file or directorty from which to look for deviation files, is mandatory.  
### input and output parameters  
`input_filepath`: str  
    a string representing one of the following:  
    - the path to the input deviation file.  
    - the path to the folder containing the deviation files, all the _.dev_ files will be processed.  
    - a pattern that will find the files to be processed.  
  
`output_filepath`: [optional] str or None  
    a string representing the path to the file where to write out the keyword.  
    if None, the same input_filepath will be used, appending the suffix *_WELL_TRAJECTORY* to the name, and using the extension *.INC*.  
    _default: `None`_  
  
`extension`: [optional] str  
    the extension for the deviation files to look for.  
    _default: '.dev'_  
  
`recursive`: [optional] bool  
    if a folder is provided as input_filepath, set recursive True to search for deviation files in subfolders.  
    _default: `True`_  

`keyword_format`: [optional] str 'echelon', 'flow', or 'resinsight'  
    Set the format of the output file to be written for Echelon simulator, OPM flow simulator, or ResInsight visualization.  
    _default: 'echelon'_  
  
`suffix`: [optional] str  
    A string to appended as suffix to the orinal file name when writting the keyword include file.
    To remove the suffix use the `bool` `False` or empty string ''.
    _default:_
        _'WELL_TRAJECTORY'_ when keyword_format='echelon'
        _'WELTRAJ'_ when keyword_format='flow'
  
### to set alternative input colums  
`md_col`: [optional] str  
    string indicating the name of the MD column in the deviation survey  
    _default: 'MD'_  
  
`x_col`: [optional] str  
    string indicating the name of the X coordinate column in the deviation survey  
    _default: 'X'_  
  
`y_col`: [optional] str  
    string indicating the name of the Y coordinate column in the deviation survey  
    _default: 'Y'_  
  
`z_col`: [optional] str  
    string indicating the name of the Z coordinate column in the deviation survey  
    _default: 'Z'_  
  
### to correct coordinates system, units, and well name case  
`output_units`: [optional] str 'field' or 'metric' or `None`
    the output will be converted to requested units, assuming original units as per the header description at the lines following these patterns:  
        - # DX DY ARE GIVEN IN * *-UNITS  
        - # DEPTH (Z, tvd_z) GIVEN IN *-UNITS
    _default: `None`_

`negate_x`, `negate_y`: [optional] bool  
    if set to True the values from X column will be multiplied by -1.  
    if `False`, will not be change.  
    _default: `False`_  
  
`negate_z`: [optional] bool  
    if set to `True` the values from Z column will be multiplied by -1. 
        - deviation surveys normally consider the vertical axes as height (positive towards the sky with reference at sea level), therefore, values below the sea level are expressed as negative numbers.  
        - ECHELON simulator considers the vertical axes positive towards the earth centre, thus, negative values from deviation surveys must be multiplied by -1 in order to intersect the grid.  
    if `False`, will not be change.  
    _default: `False`_  
  
`wellname_case`: str 'upper', 'lower' or 'title', or `None`
    A string indicating if the wellnames case should be changed, to uppercase or lowercase, or left as original.
        - 'upper' to convert the wellnames to 'UPPER CASE'.
        - 'lower' to convert the wellnames to 'lower case'.
        - 'title' to convert the wellnames to 'Title Case'.
        - None to leave the wellname as stated in the deviation survey.
    _default: `None`_
  
`convert_md_to`, `convert_x_to`, `convert_y_to`, `convert_z_to`: [optional] float, str or `None`  
 **These parameters overide the automatic conversion settings!**  
 The values provided with any of these parameters will ignore the automatic conversion from the output_units parameter.  
 The coordinates not indicated by any of the `convert_*?*_to` keywords will be reported as per their original values.  
 The alternative values accepted by these keywords are:  
    - if a float is provided, the deviation column will be multiplied by that number.  
    - if one the strings 'ft' or 'm' is provided, the corresponding multiplier to convert m->ft or ft->m will be applied.  
    - if `None`, the conversion will be based on the output_units argument and the input data inferred from the header of the deviation survey.  
    _default: `None`_