pyedna package

Submodules

pyedna.calc_config module

pyedna.calc_config

This module is meant to parse a calc config file from an eDNA service.

copyright:
  1. 2017 Eric Strong.
license:

Refer to LICENSE.txt for more information.
class pyedna.calc_config.CalcConfig(filename, site_override=None)

Bases: object

get_relationships()

Gets the relationships between calc tags and all associated tags.

Returns:a pandas DataFrame with columns: ‘FullTag’ = calculation tag ‘TagsInCalc’ = the tags that appear in the calculation
write_relationships(file_name, flat=True)

This module will output the eDNA tags which are used inside each calculation.

If flat=True, data will be written flat, like:
ADE1CA01, ADE1PI01, ADE1PI02
If flat=False, data will be written in the non-flat way, like:
ADE1CA01, ADE1PI01 ADE1CA01, ADE1PI02
Parameters:
  • file_name – the output filename to write the relationships, which should include the ‘.csv’ extension
  • flat – True or False

pyedna.ezdna module

pyedna.ezdna

This module contains “easy” versions of common functions from the eDNA C++ dll. Obtain a legal copy of the C++ eDNA dll for use.

copyright:
  1. 2017 Eric Strong.
license:

Refer to LICENSE.txt for more information.
pyedna.ezdna.DoesIDExist(tag_name)

Determines if a fully-qualified site.service.tag eDNA tag exists in any of the connected services.

Parameters:tag_name – fully-qualified (site.service.tag) eDNA tag
Returns:true if the point exists, false if the point does not exist

Example:

>>> DoesIDExist("Site.Service.Tag")
pyedna.ezdna.GetHist(tag_name, start_time, end_time, period=5, mode='raw', desc_as_label=False, label=None, high_speed=False, utc=False)

Retrieves data from eDNA history for a given tag.

Parameters:
  • tag_name – fully-qualified (site.service.tag) eDNA tag
  • start_time – must be in format mm/dd/yy hh:mm:ss
  • end_time – must be in format mm/dd/yy hh:mm:ss
  • period – specify the number of seconds for the pull interval
  • mode – “raw”, “snap”, “avg”, “interp”, “max”, “min” See eDNA documentation for more information.
  • desc_as_label – use the tag description as the column name instead of the full tag
  • label – supply a custom label to use as the DataFrame column name
  • high_speed – if True, pull millisecond data
  • utc – if True, use the integer time format instead of DateTime
Returns:

a pandas DataFrame with timestamp, value, and status
pyedna.ezdna.GetHistAvg(tag_name, start_time, end_time, period, desc_as_label=False, label=None)

Retrieves data from eDNA history for a given tag. The data will be averaged over the specified “period”.

Parameters:
  • tag_name – fully-qualified (site.service.tag) eDNA tag
  • start_time – must be in format mm/dd/yy hh:mm:ss
  • end_time – must be in format mm/dd/yy hh:mm:ss
  • period – in units of seconds (e.g. 10)
  • desc_as_label – use the tag description as the column name instead of the full tag
  • label – supply a custom label to use as the DataFrame column name
Returns:

a pandas DataFrame with timestamp, value, and status
pyedna.ezdna.GetHistInterp(tag_name, start_time, end_time, period, desc_as_label=False, label=None)

Retrieves data from eDNA history for a given tag. The data will be linearly interpolated over the specified “period”.

Parameters:
  • tag_name – fully-qualified (site.service.tag) eDNA tag
  • start_time – must be in format mm/dd/yy hh:mm:ss
  • end_time – must be in format mm/dd/yy hh:mm:ss
  • period – in units of seconds (e.g. 10)
  • desc_as_label – use the tag description as the column name instead of the full tag
  • label – supply a custom label to use as the DataFrame column name
Returns:

a pandas DataFrame with timestamp, value, and status
pyedna.ezdna.GetHistMax(tag_name, start_time, end_time, period, desc_as_label=False, label=None)

Retrieves data from eDNA history for a given tag. The maximum of the data will be found over the specified “period”.

Parameters:
  • tag_name – fully-qualified (site.service.tag) eDNA tag
  • start_time – must be in format mm/dd/yy hh:mm:ss
  • end_time – must be in format mm/dd/yy hh:mm:ss
  • period – in units of seconds (e.g. 10)
  • desc_as_label – use the tag description as the column name instead of the full tag
  • label – supply a custom label to use as the DataFrame column name
Returns:

a pandas DataFrame with timestamp, value, and status
pyedna.ezdna.GetHistMin(tag_name, start_time, end_time, period, desc_as_label=False, label=None)

Retrieves data from eDNA history for a given tag. The minimum of the data will be found over the specified “period”.

Parameters:
  • tag_name – fully-qualified (site.service.tag) eDNA tag
  • start_time – must be in format mm/dd/yy hh:mm:ss
  • end_time – must be in format mm/dd/yy hh:mm:ss
  • period – in units of seconds (e.g. 10)
  • desc_as_label – use the tag description as the column name instead of the full tag
  • label – supply a custom label to use as the DataFrame column name
Returns:

a pandas DataFrame with timestamp, value, and status
pyedna.ezdna.GetHistRaw(tag_name, start_time, end_time, high_speed=False, desc_as_label=False, label=None)

Retrieves raw data from eDNA history for a given tag.

Parameters:
  • tag_name – fully-qualified (site.service.tag) eDNA tag
  • start_time – must be in format mm/dd/yy hh:mm:ss
  • end_time – must be in format mm/dd/yy hh:mm:ss
  • high_speed – true = pull milliseconds
  • desc_as_label – use the tag description as the column name instead of the full tag
  • label – supply a custom label to use as the DataFrame column name
Returns:

a pandas DataFrame with timestamp, value, and status
pyedna.ezdna.GetHistSnap(tag_name, start_time, end_time, period, desc_as_label=False, label=None)

Retrieves data from eDNA history for a given tag. The data will be snapped to the last known value over intervals of the specified “period”.

Parameters:
  • tag_name – fully-qualified (site.service.tag) eDNA tag
  • start_time – must be in format mm/dd/yy hh:mm:ss
  • end_time – must be in format mm/dd/yy hh:mm:ss
  • period – in units of seconds (e.g. 10)
  • desc_as_label – use the tag description as the column name instead of the full tag
  • label – supply a custom label to use as the DataFrame column name
Returns:

a pandas DataFrame with timestamp, value, and status
pyedna.ezdna.GetMultipleTags(tag_list, start_time, end_time, sampling_rate=None, fill_limit=99999, verify_time=False, desc_as_label=False, utc=False)

Retrieves raw data from eDNA history for multiple tags, merging them into a single DataFrame, and resampling the data according to the specified sampling_rate.

Parameters:
  • tag_list – a list of fully-qualified (site.service.tag) eDNA tags
  • start_time – must be in format mm/dd/yy hh:mm:ss
  • end_time – must be in format mm/dd/yy hh:mm:ss
  • sampling_rate – in units of seconds
  • fill_limit – in units of data points
  • verify_time – verify that the time is not before or after the query
  • desc_as_label – use the tag description as the column name instead of the full tag
  • utc – if True, use the integer time format instead of DateTime
Returns:

a pandas DataFrame with timestamp and values
pyedna.ezdna.GetPoints(edna_service)

Obtains all the points in the edna_service, including real-time values.

Parameters:edna_service – The full Site.Service name of the eDNA service.
Returns:A pandas DataFrame of points in the form [Tag, Value, Time, Description, Units]
pyedna.ezdna.GetRTFull(tag_name)

Gets current information about a point configured in a real-time eDNA service, including current value, time, status, description, and units.

Parameters:tag_name – fully-qualified (site.service.tag) eDNA tag
Returns:tuple of: alue, time, status, statusint, description, units
pyedna.ezdna.GetServices()

Obtains all the connected eDNA services.

Returns:A pandas DataFrame of connected eDNA services in the form [Name, Description, Type, Status]
pyedna.ezdna.GetTagDescription(tag_name)

Gets the current description of a point configured in a real-time eDNA service.

Parameters:tag_name – fully-qualified (site.service.tag) eDNA tag
Returns:tag description
pyedna.ezdna.HistAppendValues(site_service, tag_name, times, values, statuses)

Appends a value to an eDNA history service. Take very careful note of the following required parameters. Any deviation from this exact format WILL cause the function to fail.

This function will append values to history, only if they are LATER than the current time of the last written data point. If this is not true, no data will be appended.

This value is strongly preferred over HistUpdateInsertValues, which will slow down data retrieval if it is used too often.

Parameters:
  • site_service – This is the history service for the eDNA tag, NOT the site.service of the tag itself. For instance, ANTARES.HISTORY, not ANTARES.ANVCALC
  • tag_name – This is the full site.service.tag. For instance, ANTARES.ANVCALC.ADE1CA02
  • times – This is a Python array of times in UTC Epoch format. For example, “1483926416” not “2016/01/01 01:01:01”. This must be an array.
  • values – A Python array of data point values for each times.
  • statuses – The status of the point. Refer to eDNA documentation for more information. Usually use ‘3’, which is ‘OK’.
pyedna.ezdna.HistUpdateInsertValues(site_service, tag_name, times, values, statuses)

CAUTION- Use HistAppendValues instead of this function, unless you know what you are doing.

Inserts a value to an eDNA history service. Take very careful note of the following required parameters. Any deviation from this exact format WILL cause the function to fail.

Parameters:
  • site_service – This is the history service for the eDNA tag, NOT the site.service of the tag itself. For instance, ANTARES.HISTORY, not ANTARES.ANVCALC
  • tag_name – This is the full site.service.tag. For instance, ANTARES.ANVCALC.ADE1CA02
  • times – This is a Python array of times in UTC Epoch format. For example, “1483926416” not “2016/01/01 01:01:01”. This must be an array.
  • values – A Python array of data point values for each times.
  • statuses – The status of the point. Refer to eDNA documentation for more information. Usually use ‘3’, which is ‘OK’.
pyedna.ezdna.LoadDll(location)

If the EzDnaApi64.dll file is not in the default location (C:Program Files (x86)eDNAEzDnaApi64.dll) then the user must specify the correct location of the file, before this module can be used.

Parameters:location – the full location of EzDnaApi64.dll, including filename
pyedna.ezdna.SelectPoint()

Opens an eDNA point picker, where the user can select a single tag.

Returns:selected tag name
pyedna.ezdna.StringToUTCTime(time_string)

Turns a DateTime string into UTC time.

Parameters:time_string – Must be the format “MM/dd/yy hh:mm:ss”
Returns:an integer representing the UTC int format

pyedna.serv module

pyedna.serv

This module contains functions within the EzDnaServApi, mainly used for direct interaction with eDNA services, such as pushing data in real-time.

copyright:
  1. 2017 Eric Strong.
license:

Refer to LICENSE.txt for more information.
pyedna.serv.AddAnalogShortIdMsecRecord(site_service, tag, time_value, msec, value, low_warn=False, high_warn=False, low_alarm=False, high_alarm=False, oor_low=False, oor_high=False, unreliable=False, manual=False)

This function will add an analog value to the specified eDNA service and tag, with many optional status definitions.

Parameters:
  • site_service – The site.service where data will be pushed
  • tag – The eDNA tag to push data. Tag only (e.g. ADE1CA01)
  • time_value – The time of the point, which MUST be in UTC Epoch format. For example, “1483926416” not “2016/01/01 01:01:01”.
  • msec – The additional milliseconds for the time_value
  • value – The value associated with the above time.
  • low_warn – TRUE if the point is in a low warning state
  • high_warn – TRUE if the point is in a high warning state
  • low_alarm – TRUE if the point is in a low alarm state
  • high_alarm – TRUE if the point is in a high alarm state
  • oor_low – TRUE if the point is out-of-range low
  • oor_high – TRUE if the point is out-of-range high
  • unreliable – TRUE if the point is unreliable
  • manual – TRUE if the point is manually set
Returns:

0, if the data push is successful
pyedna.serv.AddAnalogShortIdMsecRecordNoStatus(site_service, tag, time_value, msec, value)

This function will add an analog value to the specified eDNA service and tag, without an associated point status.

Parameters:
  • site_service – The site.service where data will be pushed
  • tag – The eDNA tag to push data. Tag only (e.g. ADE1CA01)
  • time_value – The time of the point, which MUST be in UTC Epoch format. For example, “1483926416” not “2016/01/01 01:01:01”.
  • msec – The additional milliseconds for the time_value
  • value – The value associated with the above time.
Returns:

0, if the data push is successful
pyedna.serv.AddAnalogShortIdRecord(site_service, tag, time_value, value, low_warn=False, high_warn=False, low_alarm=False, high_alarm=False, oor_low=False, oor_high=False, unreliable=False, manual=False)

This function will add an analog value to the specified eDNA service and tag, with many optional status definitions.

Parameters:
  • site_service – The site.service where data will be pushed
  • tag – The eDNA tag to push data. Tag only (e.g. ADE1CA01)
  • time_value – The time of the point, which MUST be in UTC Epoch format. For example, “1483926416” not “2016/01/01 01:01:01”.
  • value – The value associated with the above time.
  • low_warn – TRUE if the point is in a low warning state
  • high_warn – TRUE if the point is in a high warning state
  • low_alarm – TRUE if the point is in a low alarm state
  • high_alarm – TRUE if the point is in a high alarm state
  • oor_low – TRUE if the point is out-of-range low
  • oor_high – TRUE if the point is out-of-range high
  • unreliable – TRUE if the point is unreliable
  • manual – TRUE if the point is manually set
Returns:

0, if the data push is successful
pyedna.serv.AddAnalogShortIdRecordNoStatus(site_service, tag, time_value, value)

This function will add an analog value to the specified eDNA service and tag, without an associated point status.

Parameters:
  • site_service – The site.service where data will be pushed
  • tag – The eDNA tag to push data. Tag only (e.g. ADE1CA01)
  • time_value – The time of the point, which MUST be in UTC Epoch format. For example, “1483926416” not “2016/01/01 01:01:01”.
  • value – The value associated with the above time.
Returns:

0, if the data push is successful
pyedna.serv.AddDigitalShortIdMsecRecord(site_service, tag, time_value, msec, value, status_string='OK ', warn=False, chattering=False, unreliable=False, manual=False)

This function will add a digital value to the specified eDNA service and tag, including all default point status definitions.

Parameters:
  • site_service – The site.service where data will be pushed
  • tag – The eDNA tag to push data. Tag only (e.g. ADE1CA01)
  • time_value – The time of the point, which MUST be in UTC Epoch format. For example, “1483926416” not “2016/01/01 01:01:01”.
  • msec – The additional milliseconds for the time_value
  • value – should be either TRUE or FALSE
  • status_string – a string that must be EXACTLY 16 characters
  • warn – TRUE if the point is in a warning state
  • chattering – TRUE if the point is in a chattering state
  • unreliable – TRUE if the point is in an unreliable state
  • manual – TRUE if the point was manually set
Returns:

0, if the data push is successful
pyedna.serv.AddDigitalShortIdRecord(site_service, tag, time_value, value, status_string='OK ', warn=False, chattering=False, unreliable=False, manual=False)

This function will add a digital value to the specified eDNA service and tag, including all default point status definitions.

Parameters:
  • site_service – The site.service where data will be pushed
  • tag – The eDNA tag to push data. Tag only (e.g. ADE1CA01)
  • time_value – The time of the point, which MUST be in UTC Epoch format. For example, “1483926416” not “2016/01/01 01:01:01”.
  • value – should be either TRUE or FALSE
  • status_string – a string that must be EXACTLY 16 characters
  • warn – TRUE if the point is in a warning state
  • chattering – TRUE if the point is in a chattering state
  • unreliable – TRUE if the point is in an unreliable state
  • manual – TRUE if the point was manually set
Returns:

0, if the data push is successful
pyedna.serv.FlushShortIdRecords(site_service)

Flush all the queued records.

Parameters:site_service – The site.service where data was pushed
Returns:message whether function was successful
pyedna.serv.LoadDll(location)

If the EZDnaServApi64.dll file is not in the default location (C:Program Files (x86)eDNAEZDnaServApi64.dll) then the user must specify the correct location of the file, before this module can be used.

Parameters:location – full location of EZDnaServApi64.dll, including filename

Module contents

pyedna

A set of Python wrappers for functions in the eDNA API.

copyright:
  1. 2017 by Eric Strong.
license:

Refer to LICENSE.txt for more information.