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 set up the logging before importing the package, otherwise you will 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 can then be accessed by many properties like timestamp or overload. The measurement data is called “samples”. It’s accessed using the property samples or methods prefix with samples_.

The class supports the settings of “markers”. They are 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 the 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 an ini file named like the pnt file. In case one is found, it’s read automatically and your priorly set markers are available again.

To improve readability of your code, you’re 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()
altitude

Recorded altitude of SMP measurement (if any).

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 can always 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 “ground”.

detect_surface()

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

export_derivatives(file=None, snowpack_only=True, parameterization='P2015', precision=4)

Export observables derived from the SMP signal.

From the GUI, this is called with the parameterzation set in the user settings. Programmatically, Proksch 2015 is defaulted; for others you must supply the object’s .shortname property.

export_meta(file=None, include_pnt_header=False)

Export meta information of this profile into a CSV file.

When the 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:
  • file – A path-like object.
  • include_pnt_header – When True, raw pnt header fields are included too.
export_samples(file=None, precision=4, snowpack_only=False)

Export the samples of this profile into a CSV file.

When the 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.
export_samples_niviz(export_settings, file=None, precision=4)

Export the samples of this profile into a CSV file readable by niViz.

The following transformations will be applied for niViz:
  1. Remove air gap
  2. Convert from mm to cm
  3. Reproject profile to an angled slope
  4. Data thinning: keep every n-th element only
  5. Data stretching: multiply by a factor (to match a nearby snow pit height)
  6. Adapt header lines

When the 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_niviz and the csv extension.

Parameters:
  • export_settings – An object with properties “export_data_thinning”, (integer), “export_slope_angle” (float) and “export_stretch_factor” (float).
  • file – A path-like object.
  • precision – Precision (number of digits after comma) of the values. Default value is 4.

Visualization in niViz: Enter a new profile in niViz, add hardness and import the prepared CSV file. Then, by clicking on the x-axis label (e. g. “Grain size”) you should be able to switch parameters. If the SMP is not there, enter the settings / simple profile and set it as additional parameter with boundaries for the x-axis (e. g. 30, 0).

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 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 it’s 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 which results in values from beginning 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 an ini file.

Warning

An already existing ini file is overwritten with no warning.

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 beginning 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, 2012)

Implementation of poisson shot noise model

This module implements the shot noise model according to publication A Poisson shot noise model for micro-penetration of snow by Henning Löwe and Alec van Herwijnen, publicised in Cold Regions Science and Technology, Volume 70, January 2012, with one addition: As suggested in Proksch, Henning Löwe and Martin Schneebeli, publicised in Journal of Geophysical Research: Earth Surface, Volume 120, Issue 2, February 2015, the force signals are detrended before the force correlation function is computed.

snowmicropyn.loewe2012.SMP_CONE_AREA = 19.634954084936208

Default value for SnowMicroPen’s projected cone area, depends on SMP_CONE_DIAMETER.

snowmicropyn.loewe2012.SMP_CONE_DIAMETER = 5

Default value for SnowMicroPen’s cone diameter im mm.

snowmicropyn.loewe2012.calc(samples, window, overlap)

Calculation of shot noise model parameters.

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

Pandas dataframe with the columns ‘distance’, ‘force_median’, ‘L2012_lambda’, ‘L2012_f0’, ‘L2012_delta’, ‘L2012_L’. force_median: Median of force in N. lambda: Intensity of point process in mm^-1. f0: Mean rupture force in N. delta: Deflection at rupture in mm. L: Element size in mm.
snowmicropyn.loewe2012.calc_step(spatial_res, forces, cone_area=19.634954084936208)

Calculate shot noise parameters for a segment of a profile.

This is the actual implementation of the algorithm described in the publication and calculates the derived parameters for a single segment of the profile.

Parameters:
  • spatial_res – Spatial resolution of profile.
  • forces – Iterable containing the force values.
  • cone_area – Projected area of cone (tip) of SnowMicroPen in square millimeters.
Returns:

A tuple containing lambda, f0, delta and L.

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.

class snowmicropyn.parameterizations.proksch2015.Proksch2015
density(F_m, LL, lamb, f0, delta)

Calculation of density from median of force and element size.

Parameters:
  • F_m – Median of force in N.
  • LL – Element size in mm.
  • lamb – Intensity of point process in mm^-1 (unused in Proksch).
  • f0 – Mean rupture force in N (unused in Proksch).
  • delta – Deflection at rupture in mm (unused in Proksch).
Returns:

density in kg/m^3.
ssa(density, F_m, LL, lamb, f0, delta)

Calculation of SSA from density, median of force and element size.

Parameters:
  • density – Density in kg/m^3
  • F_m – Median of force in N.
  • LL – Element size in mm.
  • lamb – Intensity of point process in mm^-1 (unused in Proksch).
  • f0 – Mean rupture force in N (unused in Proksch).
  • delta – Deflection at rupture in mm (unused in Proksch).
Returns:

SSA value in m^2/kg.

SSA & Density (Calonne and Richter, 2020)

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 The RHOSSA campaign: multi-resolution monitoring of the seasonal evolution of the seasonal evolution of the structure and mechanical stability of an alpine snowpack by Neige Calonne, Bettina Richter, Henning Löwe, Cecilia Cetti, Judith ter Schure, Alec Van Herwijnen, Charles Fierz, Matthias Jaggi, and Martin Schneebeli publicised in The Cryosphere, Volume 14, 2020.

class snowmicropyn.parameterizations.calonne_richter2020.CalonneRichter2020
density(F_m, LL, lamb, f0, delta)

Calculation of density from median of force and element size.

Parameters:
  • F_m – Median of force in N.
  • LL – Element size in mm.
  • lamb – Intensity of point process in mm^-1 (unused in Calonne/Richter).
  • f0 – Mean rupture force in N (unused in Calonne/Richter).
  • delta – Deflection at rupture in mm (unused in Calonne/Richter).
Returns:

density in kg/m^3.
ssa(density, F_m, LL, lamb, f0, delta)

Calculation of SSA from density, median of force and element size.

Parameters:
  • density – Density in kg/m^3
  • F_m – Median of force in N.
  • LL – Element size in mm.
  • lamb – Intensity of point process in mm^-1 (unused in Calonne/Richter).
  • f0 – Mean rupture force in N (unused in Calonne/Richter).
  • delta – Deflection at rupture in mm (unused in Calonne/Richter).
Returns:

SSA value in m^2/kg.

Density (King, 2020)

Calculation of density.

This module implements the method to derive the density from SnowMicroPen’s signal as described in publication Local-scale variability of snow density on Arctic sea ice by King, J., Howell, S., Brady, M., Toose, P., Derksen, C., Haas, C., and Beckers, J., publicised in The Cryosphere, 14, 4323–4339, 2020.

class snowmicropyn.parameterizations.king2020.King2020a
density(F_m, LL, lamb, f0, delta)

Calculation of density from median of force and element size.

Parameters:
  • F_m – Median of force in N.
  • LL – Element size in mm.
  • lamb – Intensity of point process in mm^-1 (unused in King).
  • f0 – Mean rupture force in N (unused in King).
  • delta – Deflection at rupture in mm (unused in King).
Returns:

density in kg/m^3.
class snowmicropyn.parameterizations.king2020.King2020b
density(F_m, LL, lamb, f0, delta)

Calculation of density from median of force and element size.

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 prints lines like 2017 and (40, 41, 42, 43, 42).

class Header(*args, **kwds)

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 in cm. In use since v5.

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