API Reference

Receive Version Number and Git Hash

To receive the version of snowmicropyn and the git hash of snowmicropyn you’re using, do the following:

import snowmicropyn
version = snowmicropyn.__version__  #  e.g. '0.1.2'
hash = snowmicropyn.githash()  # e.g. '55623b2d71e7cb7...'

Receiving and logging this is useful for tracking purposes. The version and the git hash are loggend also when you import the package (using python’s standard logging facility). In case this information is crucial to you, it’s important to do logging setup before importing the package, otherwise you miss it. The other option is to do the logging yourself using the function snowmicropyn.githash() and accessing snowmicropyn.__version__.

snowmicropyn.githash()

Get the git hash of this release of snowmicropyn.

The Hash is a string. It can be None, which means you’re using a non official release of snowmicropyn.

Its Core: The Profile Class

class snowmicropyn.Profile(pnt_file, name=None)

Represents a loaded pnt file.

SnowMicroPen stores a recorded profile in a proprietary and binary format with a pnt file extension. A pnt file consists of a header with meta information and the recorded force measurement values. When a pnt file is loaded using this class, it reads this data. Meta information then can be accessed by many properties like timestamp or overload. The measurement data is called “samples”. Its accessed using the property samples or methods prefix with samples_.

The class supports the settings of “markers”. They identified by name and mark a certain distance value on the profile. You can set markers, read marker values, and remove markers. The two well known markers called “surface” and “ground” are used to determine the snowpack. Markers are not stored in a pnt file. As a fact, the pnt file is always just read and never written by the snowmicropyn package. To store marker values, this class writes ini files (*.ini) named same as the pnt file (but with its ini file extension, of course). Use the method save() to save your markers.

When a profile is loaded, the class tries to find a ini file named as the pnt file. In case one is found, it’s read automatically and your prior set markers are available again.

To improve readability of your code, your encouraged to load a profile using its static method load(). Here’s an example:

import snowmicropyn
p = snowmicropyn.Profile.load('./S13M0013.pnt')

After this call you can access the profile’s meta properties:

p.name
p.timestamp  # Timezone aware :)
p.coordinates  # WGS 84 latitude and longitude
p.spatial_resolution  # [mm]
p.overload

… and plenty more (not complete list).

To get the measurement values, you use the samples() property:

s = p.samples  # It's a pandas dataframe
print(s)

Export of data can be achieved using the methods export_meta() and export_samples(). Each method writes a file in CSV format:

p.export_meta()
p.export_samples()
amplifier_range

Returns the amplifier’s range of the SnowMicroPen used to record this profile.

amplifier_serial

Returns the amplifier’s serial number of the SnowMicroPen used to record this profile.

coordinates

Returns WGS 84 coordinates (latitude, longitude) of this profile in decimal format as a tuple ((float, float)) or None when coordinates are not available.

The coordinates are constructed by header fields of the pnt file. In case these header fields are empty or contain garbage, None is returned. You always can read the header fields yourself using the pnt_header_value() of this class for investigating what’s present in the pnt header fields.

detect_ground()

Convenience method to detect the ground. This also sets the marker called “surface”.

detect_surface()

Convenience method to detect the surface. This also sets the marker called “surface”.

export_meta(file=None, include_pnt_header=False)

Export meta information of this profile into a CSV file.

When parameter file is not provided, the default name is used which is same as the pnt file from which the profile was loaded with a suffix _meta and the csv extension.

Parameters:
export_samples(file=None, precision=4, snowpack_only=False)

Export the samples of this profile into a CSV file.

When parameter file is not provided, the default name is used which is same as the pnt file from which the profile was loaded with a suffix _samples and the csv extension.

Parameters:
  • file – A path-like object.
  • precision – Precision (number of digits after comma) of the values. Default value is 4.
  • snowpack_only – In case set to true, only samples within the markers surface and ground are exported.
gps_numsats

Returns the number of satellites available when location was determined using GPS. Acts as an indicator of location’s quality.

gps_pdop

Returns positional DOP (dilution of precision) value when location was determined using GPS. Acts as an indicator of location’s quality.

ground

Convenience property to access value of ‘ground’ marker.

ini_file

pathlib.Path instance of the ini file in which markers are saved.

This file may does not exist.

static load(pnt_file, name=None)

Loads a profile from a pnt file.

This static method loads a pnt file and also its ini file in case its available. You can pass a name for the profile if you like. When omitted (passing None), the content of the pnt header field (Pnt.Header.FILENAME) is used.

Parameters:
marker(label, fallback=<object object>)

Returns the value of a marker as a float. In case a fallback value is provided and no marker is present, the fallback value is returned. It’s recommended to pass a float fallback value. None is a valid fallback value.

Parameters:
  • label – Name of the marker requested.
  • fallback – Fallback value returned in case no marker exists for the provided name.
markers

Returns all markers on the profile (a dictionary).

The dictionary keys are of type string, the values are floats. When no markers are set, the returned dictionary is empty.

max_force()

Get maximum force value of this profile.

name

Name of this profile. Can be specified when profile is loaded or, by default, “filename” header entry of the pnt file is used.

overload

Returns the overload value configured when this profile was recorded.

The unit of this value is N (Newton).

pnt_file

pathlib.Path instance of the pnt file this data was loaded from.

pnt_header_value(pnt_header_id)

Return the value of the pnt header by its ID.

For a list of available IDs, see snowmicropyn.Pnt.Header.

remove_marker(label)

Remove a marker.

Equivalent to set_marker(label, None).

samples

Returns the samples. This is a pandas dataframe.

samples_within_distance(begin=None, end=None, relativize=False)

Get samples within a certain distance, specified by parameters begin and end

Default value for both is None and results to returns values from beginning or to the end of the profile.

Use parameter relativize in case you want to have the returned samples with distance values beginning from zero.

Parameters:
  • begin – Start of distance of interest. Default is None.
  • end – End of distance of interest. Default is None.
  • relativize – When set to True, the distance in the samples returned starts with 0.
samples_within_snowpack(relativize=True)

Returns samples within the snowpack, meaning between the values of marker “surface” and “ground”.

save()

Save markers of this profile to a ini file.

Warning

An already existing ini file is overwritten with no warning.

When no markers are set on the profile, the resulting file will be empty.

sensor_sensitivity

Returns the sensitivity of SnowMicroPen’s force sensor. The unit of this value is µC/N.

sensor_serial

Returns the serial number of the force sensor of the SnowMicroPen used.

set_marker(label, value)

Sets a marker.

When passing None``as value, the marker is removed. Otherwise, the provided value is converted into a ``float. The method raises ValueError in case this fails.

Parameters:
  • label – Name of the marker.
  • value – Value for the marker. Passing a float is recommended.
smp_firmware

Returns the firmware version of the SnowMicroPen at the time of recording this profile.

smp_length

Returns the length on the SnowMicroPen used.

smp_serial

Returns the serial number of the SnowMicroPen used to record this profile.

smp_tipdiameter

Returns the tip diameter of SnowMicroPen used.

spatial_resolution

Returns the spatial resolution of this profile in mm (millimeters).

speed

Returns the speed used to record this profile in mm/s (millimeters per second).

surface

Convenience property to access value of ‘surface’ marker.

timestamp

Returns the timestamp when this profile was recorded. The timestamp is timezone aware.

Auto-detection of Ground & Surface

snowmicropyn contains algorithms to detect begin and end of the snowpack automatically. This algorithms may fail, so you may check the values before you process your data any further.

snowmicropyn.detection.detect_ground(profile)

Automatic detection of ground (end of snowpack).

Parameters:profile (snowmicropyn.Profile) – The profile to detect ground in.
Returns:Distance where ground was detected.
Return type:float
snowmicropyn.detection.detect_surface(profile)

Automatic detection of surface (begin of snowpack).

Parameters:profile – The profile to detect surface in.
Returns:Distance where surface was detected.
Return type:float

Shot Noise Model (Löwe, 2011)

SSA & Density (Proksch, 2015)

Calculation of density and ssa.

This module implements the methods to derive density and specific surface area (SSA) from SnowMicroPen’s signal as described in publication Density, specific surface area, and correlation length of snow measured by high‐resolution penetrometry by Martin Proksch, Henning Löwe and Martin Schneebeli, publicised in Journal of Geophysical Research: Earth Surface, Volume 120, Issue 2, February 2015.

snowmicropyn.proksch2015.calc(samples, window=2.5, overlap=50)

Calculate ssa and density from a pandas dataframe containing the samples of a SnowMicroPen recording.

Parameters:
  • samples – A pandas dataframe containing the columns ‘distance’ and ‘force’.
  • window – Size of window in millimeters.
  • overlap – Overlap factor in percent.
Returns:

A pandas dataframe with the columns ‘distance’, ‘P2015_density’ and ‘P2015_ssa’.
snowmicropyn.proksch2015.calc_from_loewe2012(shotnoise_dataframe)

Calculate ssa and density from a pandas dataframe containing shot noise model values.

Parameters:shotnoise_dataframe – A pandas dataframe containing shot noise model values.
Returns:A pandas dataframe with the columns ‘distance’, ‘P2015_density’ and ‘P2015_ssa’.
snowmicropyn.proksch2015.calc_step(median_force, element_size)

Calculation of density and ssa from median of force and element size.

This is the actual math described in the publication.

Parameters:
  • median_force – Median of force.
  • element_size – Element size.
Returns:

Tuple containing density and ssa value.

Under the hood

snowmicropyn.Profile uses the method load() of class snowmicropyn.Pnt to get the raw data of pnt file. You probably won’t ever use this class yourself.

class snowmicropyn.Pnt

Low level pnt loading functionality.

An example:

from snowmicropyn import Pnt

header, raw_samples = Pnt.load('S31M0067.pnt')

print(header[Pnt.Header.TIMESTAMP_YEAR].value)
print(raw_samples[2000:2005])

This may prints lines like 2017 and (40, 41, 42, 43, 42).

class Header

Identifiers for pnt header entries

AMPLIFIER_RANGE = 'amplifier.range'

Amplifier range

AMPLIFIER_SERIAL = 'amplifier.serial'

Serial number of amplifier

AMPLIFIER_TYPE = 'amplifier.type'

Amplifier type value

BATTERY_VOLTAGE = 'battery.voltage'

Voltage of battery. NOT IN USE.

CAL_END = 'cal.end'

cal end… NOT IN USE.

CAL_START = 'cal.start'

cal start… NOT IN USE.

COMMENT_CONTENT = 'comment.content'

Comment content. NOT IN USE.

COMMENT_LENGTH = 'comment.length'

Comment length. NOT IN USE.

FILENAME = 'filename'

Filename of recording

GPS_CH1903_X = 'gps.ch1903.x'

CH1903 coordinate X. NOT IN USE.

GPS_CH1903_Y = 'gps.ch1903.y'

CH1903 coordinate Y. NOT IN USE.

GPS_CH1903_Z = 'gps.ch1903.z'

CH1903 coordinate Z. NOT IN USE.

GPS_FIXMODE = 'gps.fixmode'

GPS fix mode value

GPS_NUMSATS = 'gps.numsats'

Number of satellites when location was determined. NOT IN USE.

GPS_PDOP = 'gps.pdop'

Positional DOP, geometric dilution of precision

GPS_STATE = 'gps.state'

GPS state

GPS_WGS84_EAST = 'gps.wgs84.east'

Part of WGS 84 coordinates: E eastern, W for western.

GPS_WGS84_HEIGHT = 'gps.wgs84.height'

WGS84 altitude. NOT IN USE.

GPS_WGS84_LATITUDE = 'gps.wgs84.latitude'

WGS 84 latitude

GPS_WGS84_LONGITUDE = 'gps.wgs84.longitude'

WGS 84 longitude

GPS_WGS84_NORTH = 'gps.wgs84.north'

Part of WGS 84 coordinates: N for northern hemisphere, S for southern hemisphere

LOCAL_THETA = 'local.theta'

Local theta. NOT IN USE.

LOCAL_X = 'local.x'

Local X… NOT IN USE.

LOCAL_Y = 'local.y'

Local Y… NOT IN USE.

LOCAL_Z = 'local.z'

Local Z… NOT IN USE.

LOOPSIZE = 'loopsize'

Loop size… NOT IN USE.

RESERVED1 = 'reserved.1'

Reserved space 1

RESERVED2 = 'reserved.2'

Reserved space 2

RESERVED3 = 'reserved.3'

Reserved space 3

RESERVED4 = 'reserved.4'

Reserved space 4

SAMPLES_CONVFACTOR_FORCE = 'samples.conv.force'

Conversion factor of force

SAMPLES_CONVFACTOR_PRESSURE = 'samples.conv.pressure'

Conversion factor of pressure

SAMPLES_COUNT = 'samples.count'

Number of samples

SAMPLES_COUNT_FORCE = 'samples.force.count'

Number of force samples

SAMPLES_COUNT_TEMP = 'samples.temp.count'

Number of temperature samples. NOT IN USE.

SAMPLES_OFFSET_FORCE = 'samples.force.offset'

Offset value for force values. NOT IN USE.

SAMPLES_SPATIALRES = 'samples.spatialres'

Spatial resolution of distance

SAMPLES_SPEED = 'samples.speed'

Penetration speed

SENSOR_HANDOP = 'sensor.handop'

Hand operation. NOT IN USE.

SENSOR_OVERLOAD = 'sensor.overload'

Overload value

SENSOR_RANGE = 'sensor.range'

Sensor range

SENSOR_SENSITIVITIY = 'sensor.sensitivity'

Sensor sensitivity value

SENSOR_SERIAL = 'sensor.serial'

Serial number of sensor

SENSOR_TEMPOFFSET = 'sensor.tempoffset'

Sensor temperature offset value

SENSOR_TYPE = 'sensor.type'

Sensor type value

SMP_FIRMWARE = 'smp.firmware'

Version of firmware of SnowMicroPen used

SMP_LENGTH = 'smp.length'

SnowMicroPen’s length

SMP_SERIAL = 'smp.serial'

SnowMicroPen’s serial number

SMP_TIPDIAMETER = 'smp.diameter'

Diameter of SnowMicroPen’s tip

TIMESTAMP_DAY = 'timestamp.day'

Timestamp’s day

TIMESTAMP_HOUR = 'timestamp.hour'

Timestamp’s hour

TIMESTAMP_MINUTE = 'timestamp.minute'

Timestamp’s minute

TIMESTAMP_MONTH = 'timestamp.month'

Timestamp’s month

TIMESTAMP_SECOND = 'timestamp.second'

Timestamp’s second

TIMESTAMP_YEAR = 'timestamp.year'

Timestamp’s year

WAYPOINTS = 'waypoints'

Way points… NOT IN USE.

static load(file)

Loads the raw data of a pnt file

This is the low level method used by class snowmicropyn.Profile to load the content of a pnt file. The method returns a tuple: A header (dict) and the raw measurement values (tuple). The header dictionary contains the header entries. Each entry has a label (.label), a unit (.unit) and a actual value (.value). Each entry can be None. Mostly this is the case for unit.

Parameters:file – Path-like object