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 liketimestamp
oroverload
. The measurement data is called “samples”. It’s accessed using the propertysamples
or methods prefix withsamples_
.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 methodsave()
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()
andexport_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)
orNone
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 thepnt_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:
- Remove air gap
- Convert from mm to cm
- Reproject profile to an angled slope
- Data thinning: keep every n-th element only
- Data stretching: multiply by a factor (to match a nearby snow pit height)
- 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: - pnt_file – A path-like object.
- name – Name of the profile.
-
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 afloat
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
andend
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.
- begin – Start of distance of interest. Default is
-
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 afloat
. The method raisesValueError
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.
-
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 beNone
. Mostly this is the case for unit.Parameters: file – Path-like object
-
class