API

This part of the documentation covers all the classes and methods in the welltrajconvert package.

Data Object

class welltrajconvert.DataObject[source]

A abstract base class to work with subclasses DeviationSurvey and CalculableObject.

from_json()[source]
validate()[source]
deserialize()[source]
serialize()[source]

Deviation Survey

class welltrajconvert.DeviationSurvey[source]

Dataclass for Directional Survey Points takes a single DataObject and validates and serializes it. Then converts it into a Dataclass object of Deviation Survey points, ensuring that all the correct data types are present for later calculations.

Parameters:

  • wellId: - (required) Unique well identification id

  • md: - (required) measured depth is the actual depth of the hole drilled to any point along the wellbore or to total depth, as measured from the surface location

  • inc: - (required) inclination angle, the angular measurement that the borehole deviates from vertical.

  • azim: - (required) azimuth degrees, the hole direction is measured in degrees (0 to 360°)

  • surface_latitude: - (required) surface hole latitude

  • surface_longitude: - (required) surface hole longitude

  • tvd: - true vertical depth from surface to the survey point.

  • n_s_deviation: - north south deviation for each point in the wellbore path.

  • e_w_deviation: - east west deviation for each point in the wellbore path.

  • dls: - Dogleg severity is a measure of the change in direction of a wellbore over a defined length, measured in degrees per 100 feet of length.

  • surface_x: - Surface Easting component of the UTM coordinate

  • surface_y: - Surface Northing component of the UTM coordinate

  • x_points: - Easting component of the UTM coordinate

  • y_points: - Northing component of the UTM coordinate

  • zone_number: - Zone number of the UTM coordinate

  • zone_letter: - Zone letter of the UTM coordinate

  • latitude_points: - The latitude value of a location in the borehole. A positive value denotes north. Angle subtended with equatorial plane by a perpendicular from a point on the surface of a spheriod.

  • longitude_points: - The longitude value of a location in a borehole. A positive value denotes east. Angle measured about the spheroid axis from a local prime meridian to the meridian through the point.

  • isHorizontal: - Array of strings, Vertical Or Horizontal depending on Inclination angle point

Returns:

  • dataclass obj: - Dataclass DirectionalSurvey object

from_json()[source]
serialize()[source]
validate()[source]

validate different parameters to ensure that the data in the DataObject will work with the directional survey functions

validate_array_length()

validate the length of the array, ensure md, inc, and azim are equal lengths

validate_array_sign()

validate md and inc are not negative

validate_lat_long_range()

validate that the surface lat and long are between the acceptable ranges

validate_wellId()

validate that wellId is a string, it needs to be a single wellId value not a list or array of wellIds

validate_array_monotonic()

check if array is monotonically increasing, always increasing of staying the same

deserialize()[source]

convert dict values to their proper deserialized dict values converts lists to np.arrays if not None converts value to float if not None converts value to int if not None converts value to str if not None

__post_init__()[source]

validate all data, serialized all validated data, look in all fields and types, if type is None pass, else if type given doesnt match dataclass type raise error

Calculable Object

class welltrajconvert.CalculableObject[source]

DirectionalSurvey object with a wells directional survey info

deviation_survey_obj

Attributes: directional_survey_points (Dataclass Object) DataObject object

from_json(cls, path: PathOrStr)[source]

Pass in a json path, either a string or a Path lib path and convert to a WellboreTrajectory data obj:

>>> json_path = path/'data/example.json' # path object
# alternative:
>>> json_path = 'C:/Users/data/example.json' # str
>>> dev_obj = WellboreTrajectory.from_json(json_path) # read in json path and create data obj
>>> dev_obj.data # view raw json
{'wellId': 'well_A','md': [5600.55, 5800.0, 5900.0],'inc': [85.03, 89.91, 90.97],
 'azim': [27.59, 26.69, 26.72],'surface_latitude': 29.90829444,'surface_longitude': 47.68852083}
>>> dev_obj.deviation_survey_obj # view data obj results
DeviationSurvey(
    wellId='well_A', md=array([5600.55,5800., 5900.]), inc=array([85.03, 89.91, 90.97]),
    azim=array([27.59, 26.69, 26.72]), surface_latitude=29.90829444, surface_longitude=47.68852083,
    tvd=None, n_s_deviation=None, e_w_deviation=None, dls=None, surface_x=None, surface_y=None,
    x_points=None, y_points=None, zone_number=None, zone_letter=None, latitude_points=None,
    longitude_points=None, isHorizontal=None
)
serialize()[source]

Convert survey object to serialized json:

>>> well_dict = {
...    "wellId": "well_A",
...    "md": [5600.55, 5800.0, 5900.0],
...    "inc": [85.03, 89.91, 90.97],
...    "azim": [27.59, 26.69, 26.72],
...    "surface_latitude": 29.90829444,
...    "surface_longitude": 47.68852083
... }
>>> dev_obj = WellboreTrajectory(well_dict) # get wellbore trajectory object
>>> dev_obj.calculate_survey_points() # runs through min curve algo, calc lat lon points, and calc horizontal
>>> dev_obj.serialize() # convert data object to a serialized json string
'{"wellId": "well_A", "md": [5600.55, 5800.0, 5900.0], "inc": [85.03, 89.91, 90.97],
"azim": [27.59, 26.69, 26.72], "tvd": [0.0, 8.801411366548953, 8.033417349071017],
"e_w_deviation": [0.0, 90.86066455861472, 135.79840877475],
"n_s_deviation": [0.0, 177.2584234997277, 266.5877211334688],
"dls": [0.0, 2.4431997863679826, 1.0599929804526975],
"surface_latitude": 29.90829444, "surface_longitude": 47.68852083,
"longitude_points": [47.6885236512062, 47.68882330644181, 47.688971633323014],
"latitude_points": [29.90829435014479, 29.908775557209452, 29.90901811572951],
"zone_number": 38, "zone_letter": "R",
"x_points": [759587.9344401711, 759615.6287707286, 759629.3257951656],
"y_points": [3311661.864849136, 3311715.893216619, 3311743.120786538],
"surface_x": 759587.9344401711, "surface_y": 3311661.864849136,
"isHorizontal": ["Vertical", "Horizontal", "Horizontal"]}'

Wellbore Trajectory

class welltrajconvert.WellboreTrajectory[source]

DirectionalSurvey object with a wells directional survey info

data
deviation_survey_obj

Attributes: directional_survey_points (Dataclass Object) DataObject object

crs_transform()[source]

If surface x and y are provied instead of surface latitude and longitude then the crs_transform needs to be run. This takes in a crs input and transforms the surface x y to surface lat lon, in the WGS84 projection space.:

# with only surface x and y provided you must use the crs transform
>>> well_dict = {
...    "wellId": "well_A",
...    "md": [5600.55, 5800.0, 5900.0],
...    "inc": [85.03, 89.91, 90.97],
...    "azim": [27.59, 26.69, 26.72],
...    "surface_x": 759587.9344401711,
...    "surface_y": 3311661.864849136
... }
>>> dev_obj = WellboreTrajectory(well_dict) # get wellbore trajectory object
>>> dev_obj.crs_transform(crs_to='epsg:32638') # requires `crs_transform`
>>> dev_obj.deviation_survey_obj # view data obj
# calculates the surface lat and long
DeviationSurvey(
    wellId='well_A',
    md=array([5600.55, 5800., 5900.]),
    inc=array([85.03, 89.91, 90.97]),
    azim=array([27.59, 26.69, 26.72]),
    surface_latitude=29.90829443997491, surface_longitude=47.68852083021084,
     tvd=None, n_s_deviation=None, e_w_deviation=None, dls=None,
    surface_x=759587.9344401711, surface_y=3311661.864849136,
    x_points=None, y_points=None, zone_number=None, zone_letter=None,
    latitude_points=None, longitude_points=None, isHorizontal=None
)
minimum_curvature_algorithm()[source]

Calculate TVD, n_s_deviation, e_w_deviation, and dls values along the wellbore using md, inc, and azim arrays:

>>> well_dict = {
...    "wellId": "well_A",
...    "md": [5600.55, 5800.0, 5900.0],
...    "inc": [85.03, 89.91, 90.97],
...    "azim": [27.59, 26.69, 26.72],
...    "surface_latitude": 29.90829444,
...    "surface_longitude": 47.68852083
... }
>>> dev_obj = WellboreTrajectory(well_dict) # get wellbore trajectory object
>>> dev_obj.minimum_curvature_algorithm() # calc min curve algo
>>> dev_obj.deviation_survey_obj # view data obj
DeviationSurvey(
    wellId='well_A',
    md=array([5600.55, 5800.  , 5900.  ]),
    inc=array([85.03, 89.91, 90.97]),
    azim=array([27.59, 26.69, 26.72]),
    surface_latitude=29.90829444,
    surface_longitude=47.68852083,
    tvd=array([0., 8.80141137, 8.03341735]),
    n_s_deviation=array([0., 177.2584235 , 266.58772113]),
    e_w_deviation=array([0., 90.86066456, 135.79840877]),
    dls=array([0., 2.44319979, 1.05999298]),
    surface_x=None, surface_y=None, x_points=None, y_points=None,
    zone_number=None, zone_letter=None, latitude_points=None, longitude_points=None, isHorizontal=None
)
calculate_lat_lon_from_deviation_points()[source]

get latitude and longitude points along the wellbore using the minimum curvature algorithm generated values for the ns and ew deviations.:

# well dict with surface latitude and longitude
>>> well_dict = {
...    "wellId": "well_A",
...    "md": [5600.55, 5800.0, 5900.0],
...    "inc": [85.03, 89.91, 90.97],
...    "azim": [27.59, 26.69, 26.72],
...    "surface_latitude": 29.90829444,
...    "surface_longitude": 47.68852083
... }
>>> dev_obj = WellboreTrajectory(well_dict) # get wellbore trajectory object
>>> dev_obj.minimum_curvature_algorithm() # requires min curve
>>> dev_obj.calculate_lat_lon_from_deviation_points() # calc lat lon dev points
>>> dev_obj.deviation_survey_obj # view data obj
DeviationSurvey(
    wellId='well_A',
    md=array([5600.55, 5800.  , 5900.  ]),
    inc=array([85.03, 89.91, 90.97]),
    azim=array([27.59, 26.69, 26.72]),
    surface_latitude=29.90829444,
    surface_longitude=47.68852083,
    tvd=array([0., 8.80141137, 8.03341735]),
    n_s_deviation=array([0., 177.2584235 , 266.58772113]),
    e_w_deviation=array([0., 90.86066456, 135.79840877]),
    dls=array([0., 2.44319979, 1.05999298]),
    surface_x=759587.9344401711, surface_y=3311661.864849136,
    x_points=array([759587.93444017, 759615.62877073, 759629.32579517]),
    y_points=array([3311661.86484914, 3311715.89321662, 3311743.12078654]),
    zone_number=38, zone_letter='R',
    latitude_points=array([29.90829435, 29.90877556, 29.90901812]),
    longitude_points=array([47.68852365, 47.68882331, 47.68897163]),
    isHorizontal=None

Or with only surface x and y provided:

# with only surface x and y provided
>>> well_dict = {
...    "wellId": "well_A",
...    "md": [5600.55, 5800.0, 5900.0],
...    "inc": [85.03, 89.91, 90.97],
...    "azim": [27.59, 26.69, 26.72],
...    "surface_x": 759587.9344401711,
...    "surface_y": 3311661.864849136
... }
>>> dev_obj = WellboreTrajectory(well_dict) # get wellbore trajectory object
>>> dev_obj.crs_transform(crs_to='epsg:32638') # requires `crs_transform`
>>> dev_obj.minimum_curvature_algorithm() # requires min curve
>>> dev_obj.calculate_lat_lon_from_deviation_points() # calc lat lon dev points
>>> dev_obj.deviation_survey_obj # view data obj
DeviationSurvey(
    wellId='well_A',
    md=array([5600.55, 5800.  , 5900.  ]),
    inc=array([85.03, 89.91, 90.97]),
    azim=array([27.59, 26.69, 26.72]),
    surface_latitude=29.90829443997491, surface_longitude=47.68852083021084,
    tvd=array([0., 8.80141137, 8.03341735]),
    n_s_deviation=array([0., 177.2584235 , 266.58772113]),
    e_w_deviation=array([0., 90.86066456, 135.79840877]),
    dls=array([0., 2.44319979, 1.05999298]),
    surface_x=759587.9344606012, surface_y=3311661.864846832,
    x_points=array([759587.9344606 , 759615.62879116, 759629.3258156 ]),
    y_points=array([3311661.86484683, 3311715.89321431, 3311743.12078423]),
    zone_number=38, zone_letter='R',
    latitude_points=array([29.90829435, 29.90877556, 29.90901812]),
    longitude_points=array([47.68852365, 47.68882331, 47.68897163]),
    isHorizontal=None
)
calculate_horizontal()[source]

calculate if the inclination of the wellbore is in its horizontal section. If the wellbore inclination is greater than 88 degrees then wellbore is horizontal else the well is vertical.

calculate_survey_points()[source]

Run the minimum_curvature_algorithm, calculate_lat_lon_from_deviation_points, and calculate_horizontal methods to calculate the wells lat lon points and other attributes from provided md, inc, azim and surface lat lon or surface x y.:

# well dict with surface latitude and longitude
>>> well_dict = {
...    "wellId": "well_A",
...    "md": [5600.55, 5800.0, 5900.0],
...    "inc": [85.03, 89.91, 90.97],
...    "azim": [27.59, 26.69, 26.72],
...    "surface_latitude": 29.90829444,
...    "surface_longitude": 47.68852083
... }
>>> dev_obj = WellboreTrajectory(well_dict) # get wellbore trajectory object
>>> dev_obj.calculate_survey_points() # runs through min curve algo, calc lat lon points, and calc horizontal
>>> dev_obj.deviation_survey_obj # view data obj
DeviationSurvey(
    wellId='well_A',
    md=array([5600.55, 5800., 5900.  ]),
    inc=array([85.03, 89.91, 90.97]), azim=array([27.59, 26.69, 26.72]),
    surface_latitude=29.90829443997491, surface_longitude=47.68852083021084,
    tvd=array([0., 8.80141137, 8.03341735]),
    n_s_deviation=array([0., 177.2584235 , 266.58772113]),
    e_w_deviation=array([0., 90.86066456, 135.79840877]),
    dls=array([0., 2.44319979, 1.05999298]),
    surface_x=759587.9344606012, surface_y=3311661.864846832,
    x_points=array([759587.9344606 , 759615.62879116, 759629.3258156 ]),
    y_points=array([3311661.86484683, 3311715.89321431, 3311743.12078423]),
    zone_number=38, zone_letter='R',
    latitude_points=array([29.90829435, 29.90877556, 29.90901812]),
    longitude_points=array([47.68852365, 47.68882331, 47.68897163]),
    isHorizontal=array(['Vertical', 'Horizontal', 'Horizontal'], dtype='<U10')
)

Or with only surface x and y provided:

# with only surface x and y provided
>>> well_dict = {
...    "wellId": "well_A",
...    "md": [5600.55, 5800.0, 5900.0],
...    "inc": [85.03, 89.91, 90.97],
...    "azim": [27.59, 26.69, 26.72],
...    "surface_x": 759587.9344401711,
...    "surface_y": 3311661.864849136
... }
>>> dev_obj = WellboreTrajectory(well_dict) # get wellbore trajectory object
>>> dev_obj.crs_transform(crs_to='epsg:32638') # requires `crs_transform`
>>> dev_obj.calculate_survey_points() # runs through min curve algo, calc lat lon points, and calc horizontal
>>> dev_obj.deviation_survey_obj # view data obj
DeviationSurvey(
    wellId='well_A',
    md=array([5600.55, 5800.  , 5900.  ]),
    inc=array([85.03, 89.91, 90.97]),
    azim=array([27.59, 26.69, 26.72]),
    surface_latitude=29.90829443997491, surface_longitude=47.68852083021084,
    tvd=array([0., 8.80141137, 8.03341735]),
    n_s_deviation=array([0., 177.2584235 , 266.58772113]),
    e_w_deviation=array([0., 90.86066456, 135.79840877]),
    dls=array([0., 2.44319979, 1.05999298]),
    surface_x=759587.9344606012, surface_y=3311661.864846832,
    x_points=array([759587.9344606 , 759615.62879116, 759629.3258156 ]),
    y_points=array([3311661.86484683, 3311715.89321431, 3311743.12078423]),
    zone_number=38, zone_letter='R',
    latitude_points=array([29.90829435, 29.90877556, 29.90901812]),
    longitude_points=array([47.68852365, 47.68882331, 47.68897163]),
    isHorizontal=array(['Vertical', 'Horizontal', 'Horizontal'], dtype='<U10')
)

Data Source

class welltrajconvert.DataSource[source]
data

Accept different data types and transforms them into the wellbore trajectory data format.

from_json(cls, json_obj)[source]

Take json string and turn it into the data object used in WellTrajectory

from_dictionary(cls, dict_obj)[source]

serialize dict object to string

from_df(cls, df, wellId_name: str = None, md_name: str = None, inc_name: str = None, azim_name: str = None, surface_latitude_name: Optional[str] = None, surface_longitude_name: Optional[str] = None, surface_x_name: Optional[str] = None, surface_y_name: Optional[str] = None)[source]

convert a well survey df into dict format used in WellboreTrajectory User must specify column names for wellId, md, inc, azim, and either both surface_latitude, surface_longitude, or both surface_x, surface_y

from_csv(cls, path: PathOrStr, wellId_name: Optional[str] = None, md_name: Optional[str] = None, inc_name: Optional[str] = None, azim_name: Optional[str] = None, surface_latitude_name: Optional[str] = None, surface_longitude_name: Optional[str] = None, surface_x_name: Optional[str] = None, surface_y_name: Optional[str] = None)[source]

convert a csv path into df with required column information. User must specify column names for wellId, md, inc, azim, and either both surface_latitude, surface_longitude, or both surface_x, surface_y