<no title>

Manage site data.

class watex.site.Location(lat=None, lon=None, elev=None, datum='WGS84', epsg=None, reference_ellipsoid=23, utm_zone=None, **kwds)[source]#

Bases: object

Location class

Assert, convert coordinates lat/lon , east/north to appropriate formats.

Location does not follow the scikit-learn API in order to encompass the the syntax of pycsamt and mtpy. The latter follows the Generci Mapping Tool (GMT) API format.

Parameters:

lat (float or string (DD:MM:SS.ms)) – latitude of point
lon (float or string (DD:MM:SS.ms)) – longitude of point
east (float) – easting coordinate in meters
north (float) – northing coordinate in meters
datum (string) – well known datum ex. WGS84, NAD27, NAD83, etc.
utm_zone (Optional, string) – zone number and ‘S’ or ‘N’ e.g. ‘55S’. Defaults to the centre point of the provided points
epsg (Optional, int) – epsg number defining projection (see http://spatialreference.org/ref/ for moreinfo) Overrides utm_zone if both are provided
reference_ellipsoid (Optional, int) – reference ellipsoids is derived from Peter H. Dana’s website- http://www.utexas.edu/depts/grg/gcraft/notes/datum/elist.html Department of Geography, University of Texas at Austin Internet: pdana@mail.utexas.edu . Default is 23 constrained to WGS84.

property east#

property elev#

property lat#

property lon#

property north#

to_latlon(east=None, north=None, utm_zone=None, reference_ellipsoid=None, datum=None, epsg=None)[source]#

Project coodinate on longitude latitude once data are utm at given reference ellispoid constrained to WGS-84 by default.

Parameters:

east (float) – easting coordinate in meters
north (float) – northing coordinate in meters
utm_zone (Optional, string (##N or ##S)) – utm zone in the form of number and North or South hemisphere, 10S or 03N
datum (string, default ='WGS84') – well known datum ex. WGS84, NAD27, etc.
epsg (Optional, int) – epsg number defining projection (see http://spatialreference.org/ref/ for moreinfo) Overrides utm_zone if both are provided
reference_ellipsoid (Optional, int) – reference ellipsoids is derived from Peter H. Dana’s website- http://www.utexas.edu/depts/grg/gcraft/notes/datum/elist.html Department of Geography, University of Texas at Austin Internet: pdana@mail.utexas.edu . Default is 23 constrained to WGS84.

Returns:

proj_point – projected point in lat and lon in Datum, as decimal degrees.

Return type:

tuple(lat, lon)

static to_latlon_in(easts, norths, *, data=None, utm_zone=None, datum=None, **kws)[source]#

Convert array of longitude and latitude to array of X, y UTM coordinates.

Parameters:

lats (arraylike 1d,) – Array composed of latitude values
lons (ArrayLike 1d,) – Array composed of longitude values.
utm_zone (Optional, string) – zone number and ‘S’ or ‘N’ e.g. ‘55S’. Defaults to the centre point of the provided points,
data (pd.dataFrame) –
Accepts dataframe containing the easting and northing coordinates by specifying the columns through ‘easts’ and ‘lats’ columns.

Added in version 0.2.5.
datum (string) – well known datum ex. WGS84, NAD27, NAD83, etc.
kws (dict,) – Keywords argument passed to to_latlon().

Returns:

(lats, lons) (Iterable object composed of latitude and longitude) – coordinates.
.. versionadded:: 0.1.8

See also

watex.site.Location.to_latlon: Convert easting and northing value to latitude and longitude coordinates.

to_utm(lat=None, lon=None, datum=None, utm_zone=None, epsg=None, reference_ellipsoid=None)[source]#

Project coordinates to utm if coordinates are in degrees at given reference ellipsoid constrained to WGS84 by default.

Parameters:

lat (float or string (DD:MM:SS.ms)) – latitude of point
lon (float or string (DD:MM:SS.ms)) – longitude of point
datum (string, default='WGS84') – well known datum ex. WGS84, NAD27, NAD83, etc.
utm_zone (Optional, string) – zone number and ‘S’ or ‘N’ e.g. ‘55S’. Defaults to the centre point of the provided points
epsg (Optional, int) – epsg number defining projection (see http://spatialreference.org/ref/ for moreinfo) Overrides utm_zone if both are provided
reference_ellipsoid (Optional, int) – reference ellipsoids is derived from Peter H. Dana’s website- http://www.utexas.edu/depts/grg/gcraft/notes/datum/elist.html Department of Geography, University of Texas at Austin Internet: pdana@mail.utexas.edu . Default is 23 constrained to WGS84.

Returns:

proj_point – projected point in UTM in Datum

Return type:

tuple(easting, northing, zone)

static to_utm_in(lats, lons, *, data=None, utm_zone=None, datum=None, **kws)[source]#

Convert array of longitude and latitude to array of X, y UTM coordinates.

Parameters:

lats (arraylike 1d,) – Array composed of latitude values
lons (ArrayLike 1d,) – Array composed of longitude values.
data (pd.dataFrame) –
Accepts dataframe containing the latitude and longitude coordinates by specifying the columns through ‘lats’ and ‘lons’ columns.

Added in version 0.2.5.
utm_zone (Optional, string) – zone number and ‘S’ or ‘N’ e.g. ‘55S’. Defaults to the centre point of the provided points,
datum (string) – well known datum ex. WGS84, NAD27, NAD83, etc.
kws (dict,) – Keywords argument passed to to_utm().

Returns:

(easts, norths) (Iterable object composed of easting and northing) – coordinates.
.. versionadded:: 0.1.8

See also

watex.site.Location.to_utm: Convert longitude and latitude value to easting and northing coordinates.

property utm_zone#

class watex.site.Profile(*, utm_zone=None, coordinate_system=None, datum='WGS84', epsg=None, reference_ellipsoid=23)[source]#

Bases: object

Profile class deals with the positions collected in the survey area.

In principle, there is no exact solution between longitude/latitude to x/y coordinates. Indeed, there is no isometric map from the sphere to the plane. when you convert lon/lat coordinates from the sphere to x/y coordinates in the plane, we cannot hope that all lengths will be preserved by this operation. Therefore, we have to accept some kind of deformation. For smallish parts of earth’s surface, transverse Mercator is quite common.

By default, we use x for longitude and y for latitude. This is useful when data is passed as longitude-latitude (ll) or degree-minutes- seconds (dms) in the fit method.

Parameters:

utm_zone (Optional, string) – zone number and ‘S’ or ‘N’ e.g. ‘55S’. Default to the centre point of coordinates points in the survey area. It should be a string (##N or ##S) in the form of number and North or South hemisphere, 10S or 03N
coordinate_system (str, ['utm'|'dms'|'ll']) – The coordinate system in which the data points for the profile is collected. If not given, the auto-detection will be triggered and find the suitable coordinate system. However, it is recommended to provide it for consistency. Note that if x and y are composed of value less than 180 degrees for longitude and 90 degrees for latitude, it should be considered as longitude-latitude (ll) coordinates system. If x and y are degree-minutes-second (dms or dd:mm:ss) data, they must be specify as coordinate system in order to accept the non-numerical data before transforming to ll. If data is passed to the fit() method and dms is not specify, x and y values should be discarded.
datum (string, default = 'WGS84') – well known datum ex. WGS84, NAD27, NAD83, etc.
epsg (Optional, int) –

epsg number defining projection (
see http://spatialreference.org/ref/ for moreinfo)

Overrides utm_zone if both are provided. or https://epsg.io/?q=China%20kind%3APROJCRS
reference_ellipsoid (int, default=23) – reference ellipsoids is derived from Peter H. Dana’s website- http://www.utexas.edu/depts/grg/gcraft/notes/datum/elist.html Department of Geography, University of Texas at Austin Internet: pdana@mail.utexas.edu . Default is 23 constrained to WGS84.

Examples

>>> from watex.datasets import load_edis
>>> from watex.site import Profile
>>> xy = load_edis (samples =17 , as_frame =True , key ='latitude longitude')
>>> xy.head (2)
    longitude   latitude
0  110.485833  26.051390
1  110.486153  26.051794
>>> pro= Profile ().fit( xy.longitude, xy.latitude)
>>> pro.distance ()
62.890276656978244
>>> pro.bearing ()
35.4252016495945
>>> pro.make_xy_coordinates( )
(array([110.48583316, 110.48615319, 110.48647322, 110.48679325,
       110.48711328, 110.48743331, 110.48775334]),
 array([26.05138954, 26.05179371, 26.05219788, 26.05260205, 26.05300622,
       26.05341038, 26.05381455]))

bearing(*, to_degree=True)[source]#

Compute the bearing between two coordinates.

A bearing is a direction of one point relative to another point, usually given as an angle measured clockwise from north. In navigation, bearings are often used to determine the direction to a destination or to plot a course on a map. There are two main types of bearings: absolute bearing and relative bearing.

Relative bearing refers to the angle between the forward direction of a craft (heading) and the location of another object.
Absolute bearing refers to the angle between the magnetic north (magnetic bearing) or true north (true bearing) and an object

The bearing (\(eta\)) between two coordinates points 1(lon1, lat1) and 2 (lon2, lat2) can becalculated as:

\[eta = atan2(sin(lon2-lon1)*cos(lat2), cos(lat1)*sin(lat2) – sin(lat1)*cos(lat2)*cos(lon2-lon1))\]

By default, the first and last coordinates for points 1 and 2 are used as latlon1 and latlon2 respectively.

Parameters:: to_degree (bool, default=True) – Convert the bearing from radians to degree.
Returns:: :math:`eta` – The value of bearing in degree ( default).
Return type:: float,

distance(*, average_distance=True)[source]#

Compute the distance between profile coordinates points.

Preferably, it uses the UTM coordinates positions. By default the coordinate system is automatically detected.

Parameters:: average_distance (bool, default =True,) – Returns the average value of the distance between different points.
Returns:: d – Is the distance between points or the average of all distances.
Return type:: Arraylike of shape (N-1)

See also

watex.utils.exmath.get_distance: Get the distance from longitude/latitude or easting/northing coordinates.

Examples

>>> import numpy as np
>>> from watex.site import Profile
>>> posx = np.random.rand (7) *10
>>> posx = np.abs ( np.random.randn (7) * 12 )
>>> po= Profile().fit(posx, posy )
>>> # convert data to UTM and compute distance becuase
>>> # our toy example has value less than 90 and 180.
>>> po.distance ()
251053.3287093233
>>> po.coordinate_system = 'UTM'
>>> 6.451210308544236

static dms2ll(x, y, *, data=None)[source]#

Convert array x and y from DD:MM:SS to degree decimal -longitude (x) and latitude (y).

Parameters:

x (ArrayLike containing the degree-minutes-seconds (DMS) coordinates) – positions.
y (ArrayLike containing the degree-minutes-seconds (DMS) coordinates) – positions.

Returns:

x, y (Arraylike or str) – ArrayLike in degree decimal coordinates format. By default x and y are longitude and latitude respectively. If x and y has a string argument, data must be provided, otherwise an error raises.
data (pd.DataFrame) – DataFrame containg the position x and y.

Added in version 0.2.5.

Example

>>> from watex.site import Profile
>>> x=['20:15:35'] ; y =['7:45:8.5']
>>> Profile.dms2ll (x, y)
Out[83]: (array([20.25972222]), array([7.75236111]))

static f_(ar, /, func='dms->ll')[source]#

Converter position function from dms to longitude/latitude degree decimal or vice versa.

Convert position from str (DD:MM:SS) to float (latitude/longitude) and vice versa.

Parameters:

ar (ArrayLike 1d,) – Array containing the position coordinates for conversion.
func (Callable or str, default ='dms->ll') –
Converter functions. They can be:
- convert_position_str2float() for :dd:mm:ss to foat(long, lat) coordinates. If string is passed it should be [‘dms2ll’|’dmstoll’|’dms-<ll’].
- convert_position_float2str() from float (long, lat) in decimal degree coordinates to dd:mm:ss. When string is passed, it should be [‘ll2dms’|’lltodms’|’ll->dms’]

Returns:

Map object composed of value converted.

Return type:

generator obj.

fit(x, y, elev=None, **fit_params)[source]#

Populate profile attributes from x and y.

By default if the coordinate system is given as latitude/longitude x, y are latitude and longitude respectively.

Parameters:

x (ArrayLike 1d /str) – One dimensional arrays. x can be consider as the abscissa of the landmark and y as ordinates array. If x or y is passed as string argument, data must be passed as fit_params keyword arguments and the name of x and y must be a column name of the data. By default x and y are considered as longitude and latitude when dms or ll coordinate system is passed.
y (ArrayLike 1d /str) – One dimensional arrays. x can be consider as the abscissa of the landmark and y as ordinates array. If x or y is passed as string argument, data must be passed as fit_params keyword arguments and the name of x and y must be a column name of the data. By default x and y are considered as longitude and latitude when dms or ll coordinate system is passed.
elev (ArrayLike 1d/str) – Arraylike 1d of elevation at each positions. If not supplied should be set to null at each points. If given, it must be consistent with x and y.
data (pd.DataFrame) – Data containing x and y values as series. Then if x and y are given as string argument, their names must be included in the data columns. Otherwise an error will raise.

Returns:

self – Object of Profile.

Return type:

watex.site.Profile

Note

When data is supplied and x and y are given by their names existing in the dataframe columns, by default, the non-numerical data are removed. However, if y and x are given in DD:MM:SS in the dataframe, the coordinate system must explicitly set to ``dms` to keep the non-numerical values in the data.

property inspect#: Inspect object whether is fitted or not

interpolate(method='linear', inplace=True, **kws)[source]#

Interpolate x, y and elev ( if applicable).

Parameters:

inplace (bool, default=True) – Erase existing value of x , y and elev with the interpolated one. If False , it returns interpolated x, y and elev and keep the previous attributes x, y and elev untouchable.
method (bool, default='nearest',) – Method of interpolation. One of [‘nearest’|’linear’|’cubic’]
kws (dict,) – Additional keywords arguments passed to interpolate_grid().

Returns:

self|x, y, elev – :class:.Profile` objects if inplace is True or interpolated x, y and elev.

Return type:

Profile or Arraylikes

See also

watex.utils.funcutils.interpolate_grid: Interpolate two dimensional array.

Examples

>>> import numpy as np
>>> from watex.site import Profile
>>> x = [ 28, np.nan, 50, 60 ]
>>> y =[ np.nan, 1000, 2000, 3000]
>>> elev=[ 0, 1 , np.nan, np.nan]
>>> po = Profile().fit(x, y, elev )
>>> po.interpolate ()
>>> po.x
array([28., 39., 50., 60.])
>>> po.y
array([1000., 1000., 2000., 3000.])
>>> po.elev
array([0., 1., 1., 1.])

static ll2dms(x, y, *, data=None)[source]#

Convert array x and y from degree decimal to degree-minutes-seconds (DMS)

Parameters:

x (ArrayLike or str) – Arrays containing the degree decimal position coordinates. If x and y has a string argument, data must be provided, otherwise an error raises
y (ArrayLike or str) – Arrays containing the degree decimal position coordinates. If x and y has a string argument, data must be provided, otherwise an error raises

Returns:

x, y (Arraylike) – ArrayLike in DD:MM:SS coordinates format.
data (pd.DataFrame) – DataFrame containg the position x and y.

Added in version 0.2.5.

Example

>>> from watex.site import Profile
>>> x =[15.18 ] ; y =[19.60]
>>> Profile.ll2dms (x, y)
Out[84]: (array(['15:10:48.00'], dtype='<U11'),
          array(['19:36:00.00'], dtype='<U11'))

make_xy_coordinates(*, step=None, r=None, todms=False, **kws)[source]#

Generate synthetic coordinates from references latitude and longitude from x and y.

Parameters:

step (float or str) – Offset or the distance of seperation between different sites in meters. If the value is given as string type, except the km, it should be considered as a m value. Only meters and kilometers are accepables.
r (float or int) – The rotate angle in degrees. Rotate the angle features toward the direction of the projection profile. Default value use the bearing() value in degrees.
todms (bool, Default=False) – Reconvert the longitude/latitude degree decimal values into the DD:MM:SS.
kws (dict,) – Additional keywords of makeCoords().

Returns:

lon, lat – ArrayLike of synthetic coordinates latitude and longitude.

Return type:

ArrayLike

See also

watex.utils.coreutils.makeCoords: Create mutiple coordinates with different strategies using references latitude and longitude.

Examples

>>> import watex as wx
>>> # get two coordinates from random stations
>>> data = wx.make_erp (n_stations =2 ).frame
>>> p = Profile ().fit(data.longitude, data.latitude)
>>> longs, lats = p.make_xy_coordinates(step =100 , todms =True )
>>> longs
Out[40]: array(['-99:13:48.11', '-99:13:48.11'], dtype='<U12')
>>> lats
array(['-85:31:37.57', '-85:31:37.57'], dtype='<U12')
>>> p = Profile ().fit(data.easting, data.northing)
>>> longs, lats = p.make_xy_coordinates(step =100 , todms =True )
>>> longs, lats
Out[43]:
(array(['110:58:55.00', '110:58:55.00'], dtype='<U12'),
 array(['4:32:10.96', '4:32:10.96'], dtype='<U10'))

static out(x, y, /, elev=None, filename=None, basename=None, counter=False, sep=None, savepath=None, extension='.txt', how='py', verbose=0)[source]#

Export coordinates data.

File to export should be [‘name’ | ‘x’ |’y’ |’elev’ ].

Parameters:

x (Arraylike) – X-coordinate values to export.
y (ArrayLike,) – Y -coordinate values to export.
elev (ArrayLike,) – Elevation values to export. If not given should be null.
filename (str,) – Name of output file.
basename (str, default='Site') – Station/site name of each coordinate (x, y) position. If not given should be site.
counter (bool, default=False) – If True, count the number site and prefix it. For instance of 42 sites with the basename=AMT, the first counter site should be 00_AMT for Python indexing (``how='py')
sep (str, default =' ') – the separator between site, x, y, elev.
savepath (str,) – Output file destination. Default is current directory.
extension (str, default='.txt') – The format of output coordinates files. If the extension is suffixed with the filename, it should be used instead.
how (str, default='py') – Way for counting the site/station. Any other value should starting counting the site from 1.
verbose (int, default=False) – show message to where the file is saved.
versionadded: (..) – 0.2.1:

Examples

>>> import numpy as np
>>> import watex as wx
>>> data = wx.make_erp (n_stations=24).frame
>>> wx.site.Profile.out (data.easting, data.northing, verbose =True  )
>>> elev = np.random.permutation  (len(data.easting)) *100
>>> wx.site.Profile.out (data.easting, data.northing, elev,
                         filename ='coordinates.txt', basename ='AMT-E1',
                         counter =True )

plot(sites=None, basename='S', coerce=True, **kws)[source]#

Base plot of the profile.

Parameters:

sites (str, Arraylike) – The name of the sites that fits each position x, y
basename (str, default='S') – the text to prefix the site position when the text is not given.
coerce (bool, default=True) – Force the plot despite the given sites do not match the number of positions x and y. If False, number of positions must be consistent with x and y, otherwise error raises.
kws (dict,) – Additional keyword arguments passed to plot_text()
versionadded: (..) – 0.2.1:

scale_positions(**sp_kws)[source]#

Scale the position coordinates along x and y.

Parameters:: sp_kws (dict) – Keyword arguments passed to scalePosition().
Returns:: x, y – Scaled positions
Return type:: Arraylikes

See also

watex.utils.scalePositions: Scale positions using the scipy curve fit.
watex.utils.exmath.scale_positions: Scale and shift positions using bearing.

shift_positions(*, step=None, use_average_dist=False, angle=None)[source]#

Shift the x and y position coordinates from the step and angle.

By default, it consider x and y as easting/latitude and northing/longitude coordinates respectively. It latitude and longitude are given, specify the parameter is_latlon to True.

Parameters:

step (float, Optional) – The positions separation. If not given, the average distance between all positions should be used instead.
use_average_dist (bool, default=False,) – Use the distance computed between positions for the correction.
angle (float, Optional) – Bearing angle in degree to shift the profile line . If None, the bearing of x and y is used instead.

Returns:

xx, yy – The arrays of position correction from x and y using the bearing.

Return type:

Arraylike 1d,

See also

watex.utils.exmath.get_bearing: Compute the direction of one point relative to another point.

Examples

>>> from watex.utils.exmath import scale_positions
>>> east = [336698.731, 336714.574, 336730.305]
>>> north = [3143970.128, 3143957.934, 3143945.76]
>>> p= Profile().fit (east, north)
>>> east_c , north_c= p.scale_positions (east, north, step =20)
>>> east_c , north_c
(array([336686.69198337, 336702.53498337, 336718.26598337]),
 array([3143986.09866306, 3143973.90466306, 3143961.73066306]))

This Page