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 liketimestamp
oroverload
. The measurement data is called “samples”. Its accessed using the propertysamples
or methods prefix withsamples_
.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 methodsave()
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()
andexport_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)
) 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 always can 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 “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: - file – A `Path-like object<https://docs.python.org/3/glossary.html#term-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 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: - 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
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.
- 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 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 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 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 beNone
. Mostly this is the case for unit.Parameters: file – Path-like object
-
class