sa_gwdata docstrings

Find wells

sa_gwdata.find_wells(input_text, **kwargs)[source]

Find wells and retrieve some summary information.

Parameters:

input_text (str) – any well identifiers to parse. See sa_gwdata.parse_well_ids_plaintext() for details of other keyword arguments you can pass here.

For example:

>>> import sa_gwdata
>>> wells = sa_gwdata.find_wells("yat99 5840-46 ULE205")
...
>>> wells
['MLC008', 'ULE205', 'YAT099']
sa_gwdata.parse_well_ids_plaintext(input_text, types=('unit_no', 'obs_no'), unit_no_prefix='', obs_no_prefix='', dh_re_prefix='\\A')[source]

Parse possible well identifiers out of plain text.

Parameters:

  • input_text (str) – the text to parse well identifiers from. Can include multiple lines.

  • types (tuple) – types of identifiers to look for. Currently supported: “unit_no”, “obs_no”, “dh_no”

  • dh_re_prefix (str) – regexp pattern required before a dh_no regexp will match

Returns: a list of tuples e.g.

>>> from sa_gwdata import parse_well_ids
>>> parse_well_ids('sle15')
[('obs_no', 'SLE015')]
>>> parse_well_ids('6628150')
[]
>>> parse_well_ids('6628-150')
[('unit_no', '6628-150')]
>>> parse_well_ids('662800150')
[('unit_no', '6628-150')]
>>> parse_well_ids('259001', types=["dh_no"])
[('dh_no', '259001')]

Remember this doesn’t actually check whether these identifiers to a well in the real world; it just parses a string of text to find possible well identifiers. It’s pretty robust:

>>> parse_well_ids("SLE 15, SLE16, and also maybe 5910-1")
[('unit_no', '5910-1'), ('obs_no', 'SLE015'), ('obs_no', 'SLE016'), ('obs_no', 'YBE591')]

It has unfortunately matched “ybe 591” from the phrase “maybe 5910-1” as an obs_no.

sa_gwdata.find_wells_in_lat_lon(lats, lons, **kwargs)[source]

Find wells within a geographic area.

Parameters:

  • lats (tuple) – two decimal latitudes

  • lons (tuple) – two decimal longitudes

Returns: a list of sa_gwdata.Well objects (actually

a sa_gwdata.Wells object which very closely resembles a list).

Download data

sa_gwdata.wells_summary(wells, session=None, **kwargs)[source]

Get table of summary information for wells.

Parameters:

wells (list) – list of drillhole numbers (ints) or sa_gwdata.Well objects

Returns: pandas DataFrame with these columns:

  • dh_no (int64)

  • unit_hyphen (str)

  • unit_long (int64)

  • dh_name (str)

  • network (str)

  • obs_no (str)

  • drillhole_class (str)

  • aquifer (str)

  • orig_drilled_depth (float64)

  • orig_drilled_date (datetime64[ns])

  • max_drilled_depth (float64)

  • max_drilled_date (datetime64[ns])

  • latest_open_depth (float64)

  • latest_open_date (datetime64[ns])

  • latest_permit_no (float64)

  • cased_to (float64)

  • casing_min_diam (float64)

  • purpose (str)

  • latest_status (str)

  • latest_status_date (datetime64[ns])

  • latest_dtw (float64)

  • latest_swl (float64)

  • latest_rswl (float64)

  • latest_wl_date (datetime64[ns])

  • latest_tds (float64)

  • latest_ec (float64)

  • latest_sal_date (datetime64[ns])

  • latest_ph (float64)

  • latest_ph_date (datetime64[ns])

  • latest_yield (float64)

  • latest_yield_date (datetime64[ns])

  • easting (float64)

  • northing (float64)

  • zone (int64)

  • lon_deg (int64)

  • lon_min (int64)

  • lon_sec (float64)

  • lat_deg (int64)

  • lat_min (int64)

  • lat_sec (float64)

  • longitude (float64)

  • latitude_positive (float64)

  • latitude (float64)

  • hundred (str)

  • plan (str)

  • parcel (str)

  • cert_title (str)

  • map_250k (str)

  • map_100k (int64)

  • map_50k (int64)

  • map_10k (int64)

  • map_2_5k (str)

  • map_1k (int64)

  • water_info_exists (str)

  • salinity_exists (str)

  • water_chem_exists (str)

  • geophys_log_exists (str)

  • drillers_log_exists (str)

  • lith_log_exists (str)

sa_gwdata.water_levels(wells, pumping=False, anomalous=True, session=None, **kwargs)[source]

Get table of water level measurements for wells.

Parameters:

  • wells (list) – list of drillhole numbers (ints) or sa_gwdata.Well objects

  • pumping (bool) – include measurements flagged as “well being subject to the influence of local pumping” - default False

  • anomalous (bool) – include measurements flagged as being anomalous default True, as this can be subjective.

Returns: pandas DataFrame with these columns:

  • dh_no (int64)

  • network (str)

  • unit_long (int64)

  • aquifer (str)

  • easting (float64)

  • northing (float64)

  • zone (int64)

  • unit_hyphen (str)

  • obs_no (str)

  • obs_date (datetime64[ns])

  • dtw (float64)

  • swl (float64)

  • rswl (float64)

  • pressure (float64)

  • temperature (float64)

  • dry_ind (str)

  • anomalous_ind (str)

  • pump_ind (str)

  • measured_during (str)

  • data_source (str)

  • comments (str)

sa_gwdata.salinities(wells, session=None, **kwargs)[source]

Get table of salinity samples for wells.

Parameters:

wells (list) – list of drillhole numbers (ints) or sa_gwdata.Well objects

Returns: pandas DataFrame with these columns:

  • dh_no (int64)

  • network (str)

  • aquifer (str)

  • unit_hyphen (str)

  • unit_long (int64)

  • obs_no (str)

  • collected_date (datetime64[ns])

  • collected_time (str)

  • tds (int64)

  • ec (int64)

  • ph (float64)

  • sample_type (str)

  • anomalous_ind (str)

  • test_place (str)

  • extract_method (str)

  • measured_during (str)

  • data_source (str)

  • easting (float64)

  • northing (float64)

  • zone (int64)

sa_gwdata.water_chem(wells, session=None, **kwargs)[source]

Get table of water chemistry sample analyses for wells.

Parameters:

wells (list) – list of drillhole numbers (ints) or sa_gwdata.Well objects

Returns: pandas DataFrame with these columns:

  • dh_no (int64)

  • unit_hyphen (str)

  • obs_no (str)

  • sample_no (int64)

  • collected_date (datetime64[ns])

  • analysis_code (str)

  • analysis_name (str)

  • value (float64)

  • unit (str)

sa_gwdata.elevation_surveys(wells, session=None, **kwargs)[source]

Get table of elevation surveys for wells.

Parameters:

wells (list) – list of drillhole numbers (ints) or sa_gwdata.Well objects

Returns: pandas DataFrame with these columns:

  • dh_no (int64)

  • unit_hyphen (str)

  • obs_no (str)

  • network (str)

  • elev_date (datetime64[ns])

  • ground_elev (float64)

  • ref_elev (float64)

  • survey_meth (str)

  • vert_accuracy (float64)

  • ref_point_type (str)

  • applied_date (datetime64[ns])

  • comments (str)

sa_gwdata.construction_events(wells, session=None, **kwargs)[source]

Get table of construction events (summary data) for wells.

Parameters:

wells (list) – list of drillhole numbers (ints) or sa_gwdata.Well objects

Returns: pandas DataFrame with these columns:

  • dh_no (int64)

  • unit_hyphen (str)

  • obs_no (str)

  • completion_date (datetime64[ns])

  • total_depth (float64)

  • final_depth (float64)

  • current_depth (float64)

  • permit_no (float64)

  • backfilled (str)

  • casing_from (float64)

  • casing_to (float64)

  • casing_min_diam (float64)

  • casing_material (str)

  • pcemented (str)

  • pcement_from (float64)

  • pcement_to (float64)

  • pzone_from (float64)

  • pzone_to (float64)

  • pzone_min_diam (float64)

  • pzone_type (str)

  • pzone_material (str)

  • pzone_aperture (float64)

  • drill_from (float64)

  • drill_to (float64)

  • drill_diam (float64)

  • drill_method (str)

  • development_method (str)

  • development_duration (float64)

  • comments (str)

sa_gwdata.construction_details(wells, session=None, **kwargs)[source]

Get table of detailed information collected at time of construction of wells.

Parameters:

wells (list) – list of drillhole numbers (ints) or sa_gwdata.Well objects

Returns: dict with four pandas DataFrames. The keys, and the

columns of the DataFrames are below:

  • “water_cuts”:

    • dh_no (int64)

    • unit_hyphen (str)

    • water_cut_date (datetime64[ns])

    • depth_from (float64)

    • depth_to (float64)

    • swl (float64)

    • yield (float64)

    • test_method (str)

    • tds (float64)

    • ec (float64)

    • sample_type (str)

  • “drilling”:

    • dh_no (int64)

    • unit_hyphen (str)

    • depth_from (float64)

    • depth_to (float64)

    • hole_diam (float64)

    • drill_method (str)

    • comments (str)

  • “casing”:

    • dh_no (int64)

    • unit_hyphen (str)

    • depth_from (float64)

    • depth_to (float64)

    • casing_diam (int64)

    • casing_material (str)

    • cement_method (str)

    • cement_from (float64)

    • cement_to (float64)

    • comments (str)

  • “prod_zones”:

    • dh_no (int64)

    • unit_hyphen (str)

    • pzone_type (str)

    • depth_from (float64)

    • depth_to (float64)

    • pzone_diam (float64)

    • pzone_material (str)

    • pzone_aperture (float64)

    • comments (str)

sa_gwdata.drillers_logs(wells, session=None, **kwargs)[source]

Get table of lithological intervals from drillers logs for wells.

Parameters:

wells (list) – list of drillhole numbers (ints) or sa_gwdata.Well objects

Returns: pandas DataFrame with these columns:

  • dh_no (int64)

  • unit_hyphen (str)

  • obs_no (str)

  • log_date (datetime64[ns])

  • logger_name (str)

  • depth_from (float64)

  • depth_to (float64)

  • lith_code (str)

  • description (str)

sa_gwdata.strat_logs(wells, session=None, **kwargs)[source]

Get table of formations from the stratigraphic logs for wells.

Parameters:

wells (list) – list of drillhole numbers (ints) or sa_gwdata.Well objects

Returns: pandas DataFrame with these columns:

  • dh_no (int64)

  • unit_hyphen (str)

  • depth_from (float64)

  • depth_to (float64)

  • strat_name (str)

  • gis_code (str)

sa_gwdata.hydrostrat_logs(wells, session=None, **kwargs)[source]

Get table of formations from the hydrostratigraphic logs for wells.

Parameters:

wells (list) – list of drillhole numbers (ints) or sa_gwdata.Well objects

Returns: pandas DataFrame with these columns:

  • dh_no (int64)

  • unit_hyphen (str)

  • unit_depth_from (float64)

  • unit_depth_to (float64)

  • subunit_depth_from (float64)

  • subunit_depth_to (float64)

  • hydro_type (float64)

  • hydro_depth_to_greater_flag (str)

  • comments (str)

  • map_symbol (str)

  • strat_name (str)

  • subunit_comments (float64)

  • subunit_code (float64)

  • subunit_desc (float64)

sa_gwdata.lith_logs(wells, session=None, **kwargs)[source]

Get table of lithological logs for wells.

Parameters:

wells (list) – list of drillhole numbers (ints) or sa_gwdata.Well objects

Returns:

  • dh_no (int64)

  • unit_hyphen (str)

  • obs_no (str)

  • depth_from (float64)

  • depth_to (float64)

  • major_lith_code (str)

  • minor_lith_code (str)

  • descr (str)

Return type:

pandas DataFrame with these columns

Well identifiers

class sa_gwdata.Well(*args, **kwargs)[source]

Represents a well.

Parameters:

  • dh_no (int) – drillhole number (required)

  • unit_no (str/int) – unit number (optional)

  • obs_no (str/int) – obs number (optional)

Other keyword arguments will be set as attributes.

id

obs number if it exists, e.g. “ADE037”, if not, unit number e.g. “6628-7625”, and in the rare case that a unit number does not exist, then drillhole no. e.g. “54594”.

Type:

str

well_id

as for id

Type:

str

title

available attributes including name, e.g. “6628-7625 / ADE037 / WEST BEACH PRIMARY”.

Type:

str

obs_no

consistent zero-padded identifier e.g. “ADE037”

Type:

str

unit_hyphen

hyphenated format e.g. “6628-7625”

Type:

str

unit_long

zero-filled format as integer e.g. 662807625 or None if missing

Type:

int/None

obs_number

obs number

Type:

ObsNumber

unit_number

unit number

Type:

UnitNumber

set(dh_no, unit_no='', obs_no='', **kwargs)[source]

See Well constructor for docstring.

set_obs_number(*args)[source]

Set obswell number.

Args are passed to ObsNumber constructor.

set_unit_number(*args)[source]

Set unit number.

Args are passed to UnitNumber constructor.

to_scalar_dict()[source]

Convert Well to a dictionary containing scalar values.

Returns: dict.

Guaranteed keys are “dh_no”, “id”, “title” and “name”.

The keys present in well.unit_number.to_scalar_dict() will be added with the prefix “unit_number.”. Same for obs_number.

Any additional attributes will also be present.

path_safe_repr(remove_prefix=True)[source]

Return title containing only characters which are allowed in Windows path names.

class sa_gwdata.UnitNumber(*args)[source]

Parse a well unit number.

Parameters:

*args (str or int) – either the complete unit number or the map sheet and drillhole sequence numbers

Example:

>>> u1 = UnitNumber("6628-7625")
>>> u2 = UnitNumber("662807625")
>>> u3 = UnitNumber(662807625)
>>> u4 = UnitNumber("6628-07625")
>>> u5 = UnitNumber(6628, 7625)
>>> u6 = UnitNumber("6628", "07625")
>>> u7 = UnitNumber("G662807625")
>>> u1 == u2 == u3 == u4 == u5 == u6 == u7
True
map

10K map sheet e.g. 6628

Type:

int

seq

sequence number e.g. 7625

Type:

int

hyphen

hyphenated format e.g. “6628-7625”

Type:

str

unit_hyphen

hyphenated format e.g. “6628-7625”

Type:

str

long

zero-filled format e.g. “662807625”

Type:

str

long_int

zero-filled format as integer e.g. 662807625 or None if missing

Type:

int/None

unit_long

zero-filled format as integer e.g. 662807625 or None if missing

Type:

int/None

wilma

WILMA style e.g. “6628-07625

Type:

str

hydstra

Hydstra style e.g. “G662807625”

Type:

str

set(*args)[source]

See UnitNumber constructor for details of arguments.

class sa_gwdata.ObsNumber(*args)[source]

Parse an observation well identifier.

Parameters:

*args (str or int) – either one string, which can be either in the format ‘ADE037’ or ‘ADE-37’, etc.; or two values, either int or str, for the plan prefix (three letters referring to the hundred) and the sequence number. e.g. ‘ADE’, 37

Example:

>>> from sa_gwdata import ObsNumber
>>> o1 = ObsNumber("ADE037")
>>> o2 = ObsNumber("ADE37")
>>> o3 = ObsNumber("ADE 37")
>>> o4 = ObsNumber("ADE", 37)
>>> o1 == o2 == o3 == o4
True
plan

hundred prefix

Type:

str

seq

sequence number

Type:

int

id

consistent zero-padded identifier e.g. “YAT017”

Type:

str

egis

ENVGIS style e.g. “YAT 17”

Type:

str

obs_no

consistent zero-padded identifier e.g. “YAT017”

Type:

str

classmethod parse(*args, **kwargs)[source]

Parse an obs identifier, ignoring all parsing errors.

Arguments are the same as those for the class constructor, but all exceptions are ignored.

Returns: ObsNumber.id if successful, a blank string if not.

set(*args)[source]

See ObsNumber constructor for details of arguments.

Groundwater Data web service utilities

sa_gwdata.get_global_session(working_crs='EPSG:4326', force_new=False)[source]
class sa_gwdata.WaterConnectSession(*args, endpoint=None, sleep=2, verify=True, load_list_data=True, working_crs='EPSG:4326', **kwargs)[source]

Wrapper around repeated requests to Groundwater Data.

Parameters:

  • endpoint (str) – url endpoint for API, optional

  • sleep (int) – minimum interval between requests in seconds. Be nice, do not reduce it.

  • verify (bool) – require valid SSL certificate

Other args and kwargs are passed to request.Session constructor.

Usage:

>>> from sa_gwdata import WaterConnectSession
>>> s = WaterConnectSession()
>>> df = s.get("GetObswellNetworkData", params={"Network": "CENT_ADEL"})
get(path, app='WDDDMS', verify=None, **kwargs)[source]

HTTP GET verb to Groundwater Data.

Parameters:

path (str) – final portion of URL path off the end of self.endpoint e.g. to GET https://www.waterconnect.sa.gov.au/_layouts/15/dfw.sharepoint.wdd /WDDDMS.ashx/GetAdvancedListsData then you would use path="GetAdvancedListsData".

refresh_available_groupings()[source]

Load lists data from API. Stores them in the attributes aquifers, networks, nrm_regions, pwas, pwras.

Any calls to sa_gwdata.WaterConnectSession.get() return an sa_gwdata.Response object:

class sa_gwdata.Response[source]
property r

Return the HTTP requests.Response object.

property json

Convert the response to JSON. Returns a dict/list.

property df

If the response is a list, convert to a pandas DataFrame with columns converted into lowercase.

property df_exists

Check if JSON can be converted to a DataFrame. Returns bool.