Package References

Hilltop class

class hilltoppy.Hilltop(base_url: str, hts: str, timeout: int = 60, **kwargs)
get_collection_list()

CollectionList request method. Returns a dataframe of collection and site names associated with the hts file.

Return type:

DataFrame

get_data(sites: str | List[str], measurements: str | List[str], from_date: str | None = None, to_date: str | None = None, agg_method: str | None = None, agg_interval: str | None = None, alignment: str = '00:00', quality_codes: bool = False, apply_precision: bool = False, tstype: str | None = None)

Method to query a Hilltop web server for time series data associated with a Site and Measurement.

Parameters:

  • sites (str or list of str) – The site(s) to get the results. You can pass a single site as a string, or a list of sites.

  • measurements (str or list of str) – The measurement(s) to get the results. If multiple sites and measurements are passed, all combinations must exist in Hilltop.

  • from_date (str or None) – The start date in the format 2001-01-01. None will put it to the beginning of the time series.

  • to_date (str or None) – The end date in the format 2001-01-01. None will put it to the end of the time series.

  • agg_method (str or None) – The aggregation method to resample the data. e.g. Average, Total, Moving Average, Extrema.

  • agg_interval (str or None) – The aggregation interval for the agg_method. e.g. ‘1 day’, ‘1 week’, ‘1 month’.

  • alignment (str or None) – The start time alignment when agg_method is not None.

  • quality_codes (bool) – Should the quality codes get returned?

  • apply_precision (bool) – Should the precision according to Hilltop be applied to the data? Only use True if you’re confident that Hilltop stores the correct precision, because it is not always correct.

  • tstype (str or None) – The time series type; one of Standard, Check, or Quality.

Return type:

DataFrame

get_measurement_list(sites: str | List[str] | None = None, measurement: str | None = None)

Method to query a Hilltop server for the measurement summary of a site or sites.

Parameters:

  • sites (str, list of str, or None) – The site(s) to get the measurements. You can pass a single site as a string, a list of sites, or None to get the measurements for all available sites in the hts file.

  • measurement (str or None) – The measurement name to filter the sites by.

Return type:

DataFrame

get_measurement_names(detailed=False)

Method to get all of the available Measurement Names in the hts. When detailed=False, then the request is relatively fast but only returns the names. When detailed=True, the method runs through as many sites as necessary to get additional data about the Measurements.

Parameters:

detailed (bool) – If True, the method runs through as many sites as necessary to get additional data about the Measurements. It may take several minutes to run this query.

Return type:

DataFrame

get_site_info(sites: str | List[str] | None = None)

SiteInfo request function. Returns all of the site data for a specific site. The Hilltop sites table has tons of fields, so you never know what you’re going to get.

Parameters:

sites (str, list of str, or None) – The site(s) to get the site info. You can pass a single site as a string, a list of sites, or None to get the site info for all available sites in the hts file.

Return type:

DataFrame

get_site_list(location: str | bool | None = None, measurement: str | None = None, collection: str | None = None, site_parameters: List[str] | None = None)

SiteList request function. Returns a list of sites associated with the hts file.

Parameters:

  • location (str, bool, or None) – Should the location be returned? Only applies to the SiteList request. ‘Yes’ returns the Easting and Northing, while ‘LatLong’ returns NZGD2000 lat lon coordinates.

  • measurement (str or None) – The measurement name.

  • collection (str or None) – Get site list via a collection.

  • site_parameters (list or None) – A list of the site parameters to be returned with the SiteList request. Make a call to site_info to find all of the possible options.

Return type:

DataFrame

Legacy modules

COM module

hilltoppy.com.makepy_hilltop(hlib='Hilltop Data Access')

Function to generate the Hilltop COM module.

Parameters:

hlib (str) – The name of the COM library.

Return type:

None

hilltoppy.com.measurement_list(hts, sites=None, mtypes=None, rem_wq_sample=True)

Function to read the site names, measurement types, and units of a Hilltop hts file. Returns a DataFrame.

Parameters:

  • hts (str) – Path to the hts file.

  • sites (list or None) – A list of site names within the hts file.

  • mtypes (list or None) – A list of measurement types that should be returned.

  • rem_wq_sample (bool) – In Hilltop ‘WQ Sample’ is a measurement type placemarker for the additional sample data. It doesn’t generally apply when querying for the combo of sites/measurement types. True removes this instance from the returned DataFrame.

Return type:

DataFrame

hilltoppy.com.get_data_quantity(hts, sites=None, mtypes=None, start=None, end=None, agg_period=None, agg_n=1, fun=None, output_site_data=False, exclude_mtype=None, sites_df=None)

Function to read water quantity data from an hts file.

Parameters:

  • hts (str) – Path to the hts file.

  • sites (list) – A list of site names within the hts file.

  • mtypes (list) – A list of measurement types that should be returned.

  • start (str) – The start date to retreive from the data in ISO format (e.g. ‘2011-11-30 00:00’).

  • end (str) – The end date to retreive from the data in ISO format (e.g. ‘2011-11-30 00:00’).

  • agg_period (str) – The resample period (e.g. ‘day’, ‘month’).

  • agg_n (int) – The number of periods (e.g. 1 for 1 day).

  • fun (str) – The resampling function.

  • output_site_data (bool) – Should the sites data be output?

  • sites_df (DataFrame) – The DataFrame return from the rd_hilltop_sites function. If this is passed than rd_hilltop_sites is not run.

Return type:

DataFrame

hilltoppy.com.get_data_quality(hts, sites=None, mtypes=None, start=None, end=None, dtl_method=None, output_site_data=False, mtype_params=None, sample_params=None, sites_df=None)

Function to read water quality data from an hts file.

Parameters:

  • hts (str) – Path to the hts file.

  • sites (list) – A list of site names within the hts file.

  • mtypes (list) – A list of measurement types that should be returned.

  • start (str) – The start date to retreive from the data in ISO format (e.g. ‘2011-11-30 00:00’).

  • end (str) – The end date to retreive from the data in ISO format (e.g. ‘2011-11-30 00:00’).

  • dtl_method (None, 'standard', 'trend') – The method to use to convert values under a detection limit to numeric. None does no conversion. ‘standard’ takes half of the detection limit. ‘trend’ is meant as an output for trend analysis with includes an additional column dtl_ratio referring to the ratio of values under the detection limit.

  • output_site_data (bool) – Should the site data be output?

  • sites_df (DataFrame) – The DataFrame return from the rd_hilltop_sites function. If this is passed than rd_hilltop_sites is not run.

Return type:

DataFrame

Native Hilltop Python module

hilltoppy.hilltop.site_list(hts)

Function to return a list of sites from an hts file. Exists for consistancy.

Parameters:

hts (str) – Path to hts file.

Return type:

list

hilltoppy.hilltop.measurement_list(hts, sites=None)

Function to read all of the sites in an hts file and the associated site info.

Parameters:

  • hts (str) – Path to hts file.

  • sites (list) – A list of site names to return.

Return type:

DataFrame

hilltoppy.hilltop.get_data(hts, sites=None, mtypes=None, from_date=None, to_date=None, agg_method='Average', agg_n=1, agg_period='day', output_missing_sites=False, site_info=None)

Function to read time series from an hts file.

Parameters:

  • hts (str) – Path to the hts file.

  • sites (list) – A list of site names within the hts file.

  • mtypes (list) – A list of measurement types that should be returned.

  • from_date (str) – The start date to retreive from the data in ISO format (e.g. ‘2011-11-30 00:00’).

  • to_date (str) – The end date to retreive from the data in ISO format (e.g. ‘2011-11-30 00:00’).

  • agg_method (str) – Options are ‘’, ‘Interpolate’, ‘Average’, ‘Total’, ‘Moving Average’, and ‘EP’.

  • agg_period (str) – The resample period (e.g. ‘day’, ‘month’).

  • agg_n (int) – The number of periods (e.g. 1 for 1 day).

  • output_site_data (bool) – Should the sites data be output?

  • sites_info (DataFrame) – The DataFrame return from the get_sites_mtypes function. If this is passed than get_sites_mtypes is not run.

Return type:

DataFrame

Web service

hilltoppy.web_service.build_url(base_url: str, hts: str, request: str, site: str | None = None, measurement: str | None = None, collection: str | None = None, from_date: str | None = None, to_date: str | None = None, location: str | bool | None = None, site_parameters: List[str] | None = None, agg_method: str | None = None, agg_interval: str | None = None, alignment: str | None = None, quality_codes: bool = False, tstype: str | None = None, response_format: str | None = None, units: bool | None = None)

Function to generate the Hilltop url for the web service.

Parameters:

  • base_url (str) – root Hilltop url str.

  • hts (str) – hts file name including the .hts extension. Even if the file to be accessed is a dsn file, it must still have an hts extension for the web service.

  • request (str) – The function request.

  • site (str or None) – The site to be extracted.

  • measurement (str or None) – The measurement type name.

  • collection (str or None) – The collection name.

  • from_date (str or None) – The start date in the format 2001-01-01. None will put it to the beginning of the time series.

  • to_date (str or None) – The end date in the format 2001-01-01. None will put it to the end of the time series.

  • location (str or bool) – Should the location be returned? Only applies to the SiteList request. True returns the Easting and Northing, while ‘LatLong’ returns NZGD2000 lat lon coordinates.

  • site_parameters (list of str) – A list of the site parameters to be returned with the SiteList request.

  • agg_method (str) – The aggregation method to resample the data. e.g. Average, Total, Moving Average, Extrema.

  • agg_interval (str) – The aggregation interval for the agg_method. e.g. ‘1 day’, ‘1 week’, ‘1 month’.

  • alignment (str) – The time alignment in the form ‘00:00’.

  • quality_codes (bool) – Should the quality codes get returned from the GetData function.

  • tstype (str) – The timeseries type, one of Standard, Check or Quality

  • response_format (str) – The Hilltop response structure. Options are None, Native, or WML2. Read the Hilltop server docs for more info.

Returns:

URL string for the Hilltop web server.

Return type:

str

hilltoppy.web_service.site_list(base_url, hts, location=None, measurement=None, collection=None, site_parameters=None, timeout=60, **kwargs)

SiteList request function. Returns a list of sites associated with the hts file.

Parameters:

  • base_url (str) – root Hilltop url str.

  • hts (str) – hts file name including the .hts extension.

  • location (str or bool) – Should the location be returned? Only applies to the SiteList request. ‘Yes’ returns the Easting and Northing, while ‘LatLong’ returns NZGD2000 lat lon coordinates.

  • collection (str) – Get site list via a collection.

  • site_parameters (list) – A list of the site parameters to be returned with the SiteList request. Make a call to site_info to find all of the possible options.

  • timeout (int) – The http request timeout in seconds.

  • **kwargs – Optional keyword arguments passed to requests.

Return type:

DataFrame

hilltoppy.web_service.site_info(base_url, hts, site, timeout=60, **kwargs)

SiteInfo request function. Returns all of the site data for a specific site. The Hilltop sites table has tons of fields, so you never know what you’re going to get.

Parameters:

  • base_url (str) – root Hilltop url str.

  • hts (str) – hts file name including the .hts extension.

  • site (str or None) – The site to be extracted.

  • timeout (int) – The http request timeout in seconds.

  • **kwargs – Optional keyword arguments passed to requests.

Return type:

DataFrame

hilltoppy.web_service.collection_list(base_url, hts, timeout=60, **kwargs)

CollectionList request function. Returns a frame of collection and site names associated with the hts file.

Parameters:

  • base_url (str) – root Hilltop url str.

  • hts (str) – hts file name including the .hts extension.

  • timeout (int) – The http request timeout in seconds.

  • **kwargs – Optional keyword arguments passed to requests.

Return type:

DataFrame

hilltoppy.web_service.measurement_list(base_url, hts, site, measurement=None, timeout=60, **kwargs)

Function to query a Hilltop server for the measurement summary of a site.

Parameters:

  • base_url (str) – root Hilltop url str.

  • hts (str) – hts file name including the .hts extension. Even if the file to be accessed is a dsn file, it must still have an hts extension for the web service.

  • site (str or None) – The site to be extracted.

  • measurement (str or None) – The measurement type name.

  • timeout (int) – The http request timeout in seconds.

  • **kwargs – Optional keyword arguments passed to requests.

Return type:

DataFrame

hilltoppy.web_service.get_data(base_url, hts, site, measurement, from_date=None, to_date=None, agg_method=None, agg_interval=None, alignment='00:00', quality_codes=False, apply_precision=False, tstype=None, timeout=60, **kwargs)

Function to query a Hilltop web server for time series data associated with a Site and Measurement.

Parameters:

  • base_url (str) – root Hilltop url str.

  • hts (str) – hts file name including the .hts extension. Even if the file to be accessed is a dsn file, it must still have an hts extension for the web service.

  • request (str) – The function request.

  • site (str or None) – The site to be extracted.

  • measurement (str or None) – The measurement type name.

  • from_date (str or None) – The start date in the format 2001-01-01. None will put it to the beginning of the time series.

  • to_date (str or None) – The end date in the format 2001-01-01. None will put it to the end of the time series.

  • agg_method (str) – The aggregation method to resample the data. e.g. Average, Total, Moving Average, Extrema.

  • agg_interval (str) – The aggregation interval for the agg_method. e.g. ‘1 day’, ‘1 week’, ‘1 month’.

  • alignment (str) – The start time alignment when agg_method is not None.

  • quality_codes (bool) – Should the quality codes get returned?

  • apply_precision (bool) – Should the precision according to Hilltop be applied to the data? Only use True if you’re confident that Hilltop stores the correct precision, because it is not always correct.

  • tstype (str or None) – The time series type; one of Standard, Check, or Quality.

  • timeout (int) – The http request timeout in seconds.

  • **kwargs – Optional keyword arguments passed to requests.

Return type:

DataFrame

API Pages