airbornegeo.Survey

class Survey(data, *, line_column=None, line_type_column=None, distance_column=None, time_column=None, height_column=None, latitude_column=None, longitude_column=None, easting_column='easting', northing_column='northing', crs=None, metadata=None, copy=True)

Container for an airborne survey dataframe with its structural column names, coordinate reference system, metadata, intersection table, and lazily computed summary statistics.

Methods which add or alter a few columns operate in place on survey.data and return the survey itself, so calls can be chained, e.g. survey.along_track_distance().filter_line(...). Methods which replace the whole dataframe (block_reduce, resample, resample_as) instead return a new Survey, leaving the original untouched.

Summary statistics (region, line_counts, line_lengths, total_length, median_line_lengths, line_azimuths, mean_line_azimuths, median_line_spacings, line_point_spacings, median_point_spacings) are computed on first access and cached. The cache is cleared automatically when methods replace or restructure the dataframe, but not when survey.data is mutated directly from outside — call invalidate_cache after such external edits.

Parameters:

• data (DataFrame | GeoDataFrame) –

  the survey dataframe. Must contain projected coordinate columns; if they are not named ‘easting’/’northing’, give their names with easting_column/northing_column and they will be renamed on ingest (the rest of the package requires those literal names).

  Apart from the coordinates, no column names are assumed. Name the columns a workflow needs when building the Survey; methods which need an unset binding raise a ValueError naming the missing one.

• line_column (str | None) – name of the column containing line names/numbers, by default None

• line_type_column (str | None) – name of the column containing line type codes (0 = flight line, 1 = tie line, 2 = excluded), by default None

• distance_column (str | None) – name of the column containing distance along line, by default None

• time_column (str | None) – name of the column containing time values, by default None

• height_column (str | None) – name of the column containing flight heights, by default None

• latitude_column (str | None) – names of the geodetic latitude/longitude columns, by default None

• longitude_column (str | None) – names of the geodetic latitude/longitude columns, by default None

• easting_column (str) – names of the projected coordinate columns in the supplied dataframe, renamed to ‘easting’/’northing’ on ingest, by default already ‘easting’/’northing’

• northing_column (str) – names of the projected coordinate columns in the supplied dataframe, renamed to ‘easting’/’northing’ on ingest, by default already ‘easting’/’northing’

• crs (Any | None) – coordinate reference system, anything accepted by pyproj.CRS.from_user_input. Taken from the GeoDataFrame if not given, by default None

• metadata (dict[str, Any] | None) – free-form survey metadata (name, year, instrument, units, …), by default None

• copy (bool) – copy the dataframe on ingest so in-place methods never alter the caller’s frame. Set to False to avoid the copy for very large surveys, at the cost of methods mutating the supplied frame, by default True

__init__(data, *, line_column=None, line_type_column=None, distance_column=None, time_column=None, height_column=None, latitude_column=None, longitude_column=None, easting_column='easting', northing_column='northing', crs=None, metadata=None, copy=True)

Parameters:

• data (DataFrame | GeoDataFrame)

• line_column (str | None)

• line_type_column (str | None)

• distance_column (str | None)

• time_column (str | None)

• height_column (str | None)

• latitude_column (str | None)

• longitude_column (str | None)

• easting_column (str)

• northing_column (str)

• crs (Any | None)

• metadata (dict[str, Any] | None)

• copy (bool)

Methods

__init__(data, *[, line_column, ...])
add_intersections(**kwargs)	Insert the intersection points as rows into the survey dataframe and add their along-line distances to the intersection table.
add_values_to_intersections(columns)	Add each line's values of the given columns to the intersection table.
along_track_distance(**kwargs)	Compute distance along each line, written to the survey's distance column.
alternating_iterative_line_levelling(*, data_col)	Alternately level flight lines (line type 0) and tie lines (line type 1) using crossover errors, written to levelled_col (default '<data_col>_levelled'); updates the survey dataframe and the intersection table in place.
block_reduce(reduction, *, spacing[, reduce_by])	Return a new Survey with block-reduced data; this survey is unchanged and its intersection table is not carried over.
calculate_crossover_errors(*, data_col, **kwargs)	Calculate crossover errors of data_col, added to the intersection table as a crossover_error_N column.
create_intersection_table(*, method, **kwargs)	Create the intersection table of the survey's lines, stored as survey.intersections.
crossover_network_levelling(*, data_col[, ...])	Network-level all lines using crossover errors, written to levelled_col (default '<data_col>_levelled'); updates the survey dataframe and the intersection table in place.
crossover_pair_levelling(*, data_col, ...[, ...])	Level the given lines to the rest of the survey using crossover errors, written to levelled_col (default '<data_col>_levelled'); updates the survey dataframe and the intersection table in place.
describe()	Compute all summary statistics and return them as a formatted string.
directional_velocity(*[, coordinate_column, ...])	Compute velocity along one coordinate direction, written to result_column (default '<coordinate_column>_velocity').
eotvos_correction(*[, method, ...])	Compute the Eötvös correction, written to result_column.
eq_sources_1d(*, data_column, damping, **kwargs)	Fit equivalent sources along each line and return them (a dict keyed by line name), for use with upward_continue_by_line or update_intersections_with_eq_sources.
equivalent_source_levelling(*, data_column, ...)	Level lines with iteratively fitted equivalent sources, written to result_column (default '<data_column>_levelled').
filter_line(*, data_column, filter_width[, ...])	Filter a data column along each line, written to result_column (default '<data_column>_filtered').
from_csv(path, **kwargs)	Reload a survey saved with to_csv.
from_parquet(path, **kwargs)	Reload a survey saved with to_parquet.
ground_speed(*[, result_column])	Compute ground speed along each line, written to result_column.
igrf(*, datetime_column[, result_columns])	Compute the IGRF intensity, inclination and declination, written to the three result_columns.
inspect_intersections(*, plot_variable[, x])	Step through a plotly profile of each line with intersections in turn, plotted against x (default the survey's distance column).
inspect_lines(*, plot_variable[, interp_on])	Step through a plotly profile of each line in turn, plotted against interp_on (default the survey's distance column).
interpolate_intersections(*, to_interp[, ...])	Interpolate to_interp onto the intersection rows along interp_on (default the survey's distance column), updating both the survey dataframe and the intersection table.
interpolate_missing(*, to_interp[, interp_on])	Fill NaN values of to_interp by interpolating along interp_on (default the survey's distance column) for each line.
interpolate_missing_pointwise(*, to_interp)	Fill NaN values of to_interp one point at a time by interpolating along interp_on (default the survey's distance column) for each line.
interpolate_missing_pointwise_with_windows(*, ...)	Fill NaN values of to_interp one point at a time using a moving window along interp_on (default the survey's distance column) for each line.
invalidate_cache()	Drop all cached statistics so they recompute on next access.
level_to_grid(*, data_column, grid_column[, ...])	Level a data column to values sampled from a grid, written to result_column (default '<data_column>_levelled').
lines_without_intersections()	Return the lines which have no intersections in the intersection table.
plot(*[, ax, color_by, categorical, ...])	Plot the survey points in map view, optionally colored by a column.
plot_line_and_crosses(*, y[, x])	Plot one line's profiles against x (default the survey's distance column), marking its intersections.
plot_profiles(*, y[, x])	Plot data profiles with matplotlib, against x (default the survey's distance column).
plotly_points(**kwargs)	Interactive map-view scatter of the survey points.
plotly_profiles(*, y[, x])	Plot data profiles with plotly, against x (default the survey's distance column).
relative_distance(*[, result_column])	Compute the distance between consecutive points of each line, written to result_column.
reproject(output_crs, *[, input_crs])	Reproject the survey's easting/northing columns into output_crs and set it as the survey's crs.
resample(*, spacing, maxdist[, resample_by])	Return a new Survey resampled onto a regular spacing of resample_by (default the survey's distance column); this survey is unchanged and its intersection table is not carried over.
resample_as(*, resample_values[, resample_by])	Return a new Survey resampled onto the supplied values of resample_by (default the survey's distance column); this survey is unchanged and its intersection table is not carried over.
sample_grid(grid, *, result_column[, ...])	Sample a grid at the survey's coordinates, written to result_column.
split_into_segments(threshold, *[, ...])	Split the survey into segments where column_name (default the survey's time column) jumps by more than threshold, writing the segment names to result_column (default the survey's line column).
to_csv(path, **kwargs)	Save this survey to CSV: <path>.csv (the data, a plain CSV file readable without airbornegeo), <path>_intersections.csv (only written if intersections is set, with its geometry column as WKT text), and <path>.json (a sidecar with the CRS, metadata, and column bindings needed to reconstruct the Survey).
to_parquet(path, **kwargs)	Save this survey to Parquet: <path>.parquet (the data, a plain Parquet file readable without airbornegeo), ``<path>_intersections.
track(*[, result_column])	Compute the travel azimuth (track) along each line, written to result_column.
unique_line_id()	Replace the line column's values with unique sequential integer ids.
update_intersections_with_eq_sources(*, ...)	Replace the interpolated values at the intersection rows with values predicted by fitted equivalent sources, written to result_column (default overwriting data_column).
upward_continue_by_line(...[, result_column])	Upward continue each line to a constant height using fitted equivalent sources, written to result_column.
vertical_acceleration(*[, result_column])	Compute vertical acceleration along each line, written to result_column.

Attributes

data	The survey dataframe.
distance_column	Name of the distance-along-line column.
height_column	Name of the flight height column.
line_azimuths	Compass azimuth (degrees clockwise from north, axial 0-180 range) of each line's minimum rotated bounding box long axis, indexed by line.
line_column	Name of the line name/number column.
line_counts	Number of lines, in total and per line type.
line_lengths	Largest bounding dimension of each line, indexed by line.
line_point_spacings	Median along-line distance between successive data points of each line, indexed by line.
line_type_column	Name of the line type code column (0 = flight, 1 = tie, 2 = excluded).
mean_line_azimuths	Mean compass azimuth per line type, computed as an axial circular mean so lines straddling the 0/180 wraparound average correctly.
median_line_lengths	Median line length per line type.
median_line_spacings	Median line spacing per line type (line types with fewer than 2 lines are skipped).
median_point_spacings	Median along-line data point spacing per line type.
region	Bounding region (west, east, south, north) of the survey.
time_column	Name of the time column.
total_length	Total survey length; the sum of all line lengths.