Interpretation¶

Interpretation in this context primarily means picking layers (either isochrones or the bed). In the future, this functionality may be expanded to make picking other things, e.g. some discontinuity, easier.

Functions used for picking¶

Functions that are a for the mechanics of picking, not for the display.

impdar.lib.picklib.auto_pick(dat, snums, tnums)¶

Automatically pick any number of reflectors.

Parameters

dat (object class) – data object
indices (numpy.ndarray) – indices on the left side of the image where the picks will start from These are the centerpoint of the wavelet

Returns

The picks selected. Rows are: top of packet, center pick, bottom of packet, time (deprecated, all nans), and power. Size 5xtnum

Return type

numpy.ndarray

impdar.lib.picklib.get_intersection(data_main, data_cross, multiple_int=True, return_nans=False, cutoff=10.0)¶

Find the intersection of two radar datasets.

Used for plotting up where pick depths at places where two profiles cross. This is a pretty simple function as implemented, so it is not going to find you multiple intersections. Rather, you are just going to get the single point where the traces are closest. Note that this will work picking sequential profiles too. If there are nans at the intersection, we look for the closest non-nan.

Parameters

data_main (impdar.lib.RadarData.RadarData) – The RadarData object upon which you want the intersection in reference to (i.e. then one you will plot up)
data_cross (impdar.lib.RadarData.RadarData) – The crossprofile from which you are going to plot up layers. Must have some picks in it.
return_nans (bool, optional) – Return the closest sample, even if it was nanpicked. Default is false (find closest non-nan value)
cutoff (float, optional) – The maximum distance for multiple intersections.

Returns

np.ndarray (npicks,) or (npicks, m) – The tracenumber in the main profile at which we are getting the sample from the crossprofile
np.ndarray (npicks,) or (npicks, m) – The depths (in sample number) of the layers in the cross profile. Note that this essentially assume you are using the same snum/depth conversion between the two profiles.

Raises

AttributeError: – if there are no picks in the cross profile.

impdar.lib.picklib.packet_pick(trace, pickparams, midpoint)¶

Really do the picking.

This is where we look for the highest amplitude return, and the opposite polarity returns surrounding it

Parameters

trace (1d numpy.ndarray) – The trace in which we are looking for our return
pickparams (impdar.lib.PickParameters.PickParameters) – The information about picking that we need for determining window size and polarity
midpoint (int) – The guess at the index where a pick is, used for searching out the highest amplitude return

Returns

len=5. Top of packet, middle of packet, bottom of packet, nan, power

Return type

list

impdar.lib.picklib.packet_power(trace, plength, midpoint)¶

Return power of a packet.

This function is pretty boring. It just finds a window around a point in a trace.

Parameters

trace (numpy.ndarray) – (snum,) The trace in which to find the window
plength (float) – The size of the packet (in samples)
midpoint (int) – The central sample

Returns

numpy.ndarray – The packet of length plength
int – The index of the top sample (desirable for calculating overall indices in functions that call this one).

impdar.lib.picklib.pick(traces, snum_start, snum_end, pickparams)¶

Pick a reflector in some traces.

Uses a line between the starting and ending picks to guide picking the maximum (or minimum) return, and the surrounding peaks with opposite polarity.

Parameters

traces (numpy.ndarray) – The chunk of data we are picking. Should be a slice of the overall data with shape snum x (size to pick)
snum_start (int) – The index of the pick in the leftmost trace. We would normally get this from the last pick.
snum_end (int) – The index of the pick in the rightmost trace.
pickparams (impdar.lib.PickParameters.PickParameters) – Use for polarity, frequency, plength.

Returns

The picks selected. Rows are: top of packet, center pick, bottom of packet, time (deprecated, all nans), and power. Size 5xtnum

Return type

numpy.ndarray

Classes used by interpreter¶

These classes are broken down to match the structure of StODeep, so we store information about how the picks get made, and the picks themselves, using different objects.

If you have done some interpretation, you will likely want to subsequently interact with the Picks object. Often, this can be done without accessing the API by converting the picks/geospatial data to another form, e.g. with impdar convert shp fn_picked.mat. You can also make plots with the picks on top of the radar data, or with the return power in geospatial coordinates, using impplot rg fn_picked.mat or impplot power fn_picked.mat layer_num. For further operations, you will probably want to access the Picks object described next. For example, using the picks object you could do something like

import numy as np
import matplotlib.pyplot as plt
from impdar.lib import RadarData
rd = RadarData('[PICKED_DATA_FN.mat]')

# make a basic plot of the radargram
fig, ax = plt.subplots()
im, _, _, _, _ = plot.plot_radargram(rd, fig=fig, ax=ax, xdat='dist', ydat='depth', return_plotinfo=True)

# calculate the return power
c = 10. * np.log10(rd.picks.power[0, :])
c -= np.nanmax(c)

# plot the return power on the layer, being careful of NaNs
mask = ~np.isnan(rd.picks.samp1[0, :])
cm = ax.scatter(rd.dist[mask.flatten()],
                rd.nmo_depth[rd.picks.samp1[0, :].astype(int)[mask]],
                c=c.flatten()[mask.flatten()],
                s=1)

The Picks structure tracks picks and picking parameters.

class impdar.lib.Picks.Picks(radardata, pick_struct=None)¶

Information about picks.

This object holds all picks for a given radargram. The main containers are matrices holding information about the indices in the data matrix a given pick lies.

samp1¶

Min/max above the center of each pick. A new row for each new pick.

Type: nsamp x tnum array

samp2¶

Max/min at the center of each pick. A new row for each new pick.

Type: nsamp x tnum array

samp3¶

Max/min below the center of each pick. A new row for each new pick.

Type: nsamp x tnum array

time¶

In StoDeep used to contain TWTT samp2. Since this is redundant I’m deptrecating it, and it will be zeros for impdar processed data.

Type: nsamp x tnum array

power¶

Power across a pick. To get this in decibels, you need to take 10. * np.log10(power)

Type: nsamp x tnum array

picknums¶

The number of each pick.

Type: list of length nsamp

lasttrace¶

Information about the end of the trace

Type: impdar.lib.LastTrace.LastTrace

lt¶

StoDeep legacy for compatibility, unused

Type: impdar.lib.LeaderTrailer.LeaderTrailer

pickparams¶

This structure contains important information used in picking, such as frequency for picks.

Type: impdar.lib.PickParameters.PickParameters

add_pick(picknum=0)¶

Add a new pick.

This method handles any complexity in adding a new pick. If no picks exist, it creates the matrices. Otherwise, it just adds rows. If the last pick hasn’t been used, this just recycles that pick.

Parameters: picknum (int, optional) – Number to call the new pick. Default zero
Returns: index – The index of the row number containing the new pick
Return type: int
Raises: ValueError if the picknum already exists--we do not deal with repeats –

crop(ind)¶

Crop the picks.

This is just subtraction with some bounds checks. It is easy since we assume that the work to convert to indices has already been done. Not needed for bottom crops.

Parameters: ind (int or ndarray(tnum, ):) – How much we need to shift by

hcrop(limits)¶

Crop to limits.

Called by the overall RadarData.hcrop

reverse()¶

Flip left-right.

Called by the overall RadarData.reverse

smooth(lowpass, units='tnum')¶

Smooth the picks.

For now there are no choices on the filter–it is 3rd order Butterworth. Picks that have NaNs in the middle are left alone–this avoids edge effects. Power is not recalculated–too much risk of bias. Do manually at own risk.

Parameters

lowpass (float) – The cutoff value for filtering, in units determined by ‘units’
units (str, optional) – The units in which lowpass are provided. Choices are tnum or dist, default tnum.

Raises

ValueError – If the wavelength is less than 1 or greater than tnum. If the units are not in [dist, tnum].
ImpDARError – If units are dist but the data are not constant spaced. If the data have been elevation corrected.

to_struct()¶

Convert to a format writable to a .mat file.

Returns: mat – Dictionary of attributes for export with scipy.io.savemat
Return type: dict

update_pick(picknum, pick_info)¶

Update a pick with new information.

Rather than go in and manually update a pick every time it is changed, we take in all information about an individual pick simultaneously and this method updates the pick’s information in the Pick object.

Parameters

picknum (int) – The pick number to update. Must be in picknums
pick_info (5xtnum np.ndarray) – Array where rows are upper pick bound, pick center, lower pick bound, time (deprecated, usually left as zeros or nans), and power across the pick.

Raises

ValueError if picknum is not in picknums or if the shape of the –
pick_info is bad. –

Structure with input data for the picking algoriths.

class impdar.lib.PickParameters.PickParameters(radardata, pickparams_struct=None)¶

Some information used for determining for picks.

This object contains several things that you need to know in order to pick a radar layer, like the frequency of layers you are looking for and the size window in which to search.

apickthresh¶

Some kind of auto picking threshold (Unused: default 10)

Type: float

freq¶

Frequency of the layer pick (default 4)

Type: float

dt¶

Time between acquisitions

Type: float

plength¶

The total packet to search for peaks

Type: float

FWW¶

The width of the center portion which we are going to search

Type: float

scst¶

The offset which we will search at

Type: float

pol¶

Polarity of the picks

Type: int

apickflag¶

I think this just kept track of whether StoDeep was autopicking

Type: int

addpicktype¶

Some flag

Type: str

radardata¶

A link back up to the RadarData object with which this is affiliated

Type: RadarData

freq_update(freq)¶

Update the frequency at which we are looking.

This is more complicated than just setting freq because other variables are a function of frequency and if not updated will break.