sa_gwdata developer guide

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, 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

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: pandas DataFrame with these columns:

  • 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)

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. “NOA002”, if not, unit number e.g. “6628-123”, and in the rare case that a unit number does not exist, then drillhole no. e.g. “200135”.

Type:str
title

available attributes including name, e.g. “7025-3985 / WRG038 / WESTERN LAGOON”.

Type:str
obs_no

obs number

Type:ObsNo
unit_no

unit number

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

See Well constructor for docstring.

set_obs_no(*args)[source]

Set obswell number.

Args are passed to ObsNo constructor.

set_unit_no(*args)[source]

Set unit number.

Args are passed to UnitNo 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_no.to_scalar_dict() will be added with the prefix “unit_no.”. Same for obs_no.

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.UnitNo(*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 = UnitNo("6628-123")
>>> u2 = UnitNo("662800123")
>>> u3 = UnitNo(662800123)
>>> u4 = UnitNo("6628-00123")
>>> u5 = UnitNo(6628, 123)
>>> u6 = UnitNo("6628", "00123")
>>> u7 = UnitNo("G662800123")
>>> u1 == u2 == u3 == u4 == u5 == u6 == u7
True
map

10K map sheet

Type:int
seq

sequence number

Type:int
hyphen

hyphenated format e.g. “6628-123”

Type:str
long

zero-filled format e.g. “662800123”

Type:str
long_int

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

Type:int/None
wilma

WILMA style e.g. “6628-00123”

Type:str
hydstra

Hydstra style e.g. “G662800123”

Type:str
set(*args)[source]

See UnitNo constructor for details of arguments.

class sa_gwdata.ObsNo(*args)[source]

Parse an observation well identifier.

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

Example:

>>> from sa_gwdata import ObsNo
>>> o1 = ObsNo("YAT017")
>>> o2 = ObsNo("YAT17")
>>> o3 = ObsNo("YAT 17")
>>> o4 = ObsNo("YAT", 17)
>>> 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
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: ObsNo.id if successful, a blank string if not.

set(*args)[source]

See ObsNo constructor for details of arguments.

WaterConnect web service utilities

class sa_gwdata.WaterConnectSession(*args, endpoint=None, sleep=2, verify=True, load_list_data=True, **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
>>> with WaterConnectSession() as s:
...     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]
r

Return the HTTP requests.Response object.

json

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

df

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

df_exists

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