airbornegeo.crossover_network_levelling#
- crossover_network_levelling(data, inters, *, data_col, levelled_col, line_column, distance_column, degree=None, filter_kwargs=None, lines_to_level=None, intersection_weight_col=None, crossover_error_interp_method='linear', relaxation_factor=0.5, raise_error_if_unchanged=True, max_iterations=5, rms_tolerance=None, rms_percent_change_tolerance=10, rms_percent_increase_tolerance=20, plot_convergence=True, plot_dynamic_convergence=False, progressbar=True)[source]#
Level a network of lines by fitting a trend (or low-pass filter) to the cross-over errors at every intersection each line participates in, whether it appears as line1 or line2 in the intersection table (i.e. method=’network’ from create_intersection_table).
This differs from crossover_pair_levelling, which levels one group of lines onto a second, fixed, reference group (method=’groups’). In a network, every line can intersect many other lines, all of which are simultaneously being adjusted, so a line’s correction is derived from all of its misties (signed so that a positive mistie always means “this line is higher than the intersecting line”), and only a fraction of the correction (relaxation_factor) is removed per iteration — splitting the mistie between both intersecting lines rather than pushing it fully onto one of them. Repeated iterations (controlled by max_iterations, as with crossover_pair_levelling) let corrections propagate through the network until the cross-over misfits converge.
- Parameters:
data (
DataFrame) – Survey dataframe with intersection rows added by add_intersections() and interpolated with interpolate_intersections().inters (
DataFrame) – Intersection table created with create_intersection_table(…, method=’network’).data_col (
str) – Column containing the values to level.levelled_col (
str) – Column name to store the levelled values in.line_column (
str) – Column containing the line / flight / segment names.distance_column (
str) – Column containing the distance along each line / segment.degree (
int|None) – Polynomial degree used to fit a trend to the misties along each line.filter_kwargs (
dict[str,Any] |None) – Alternative to degree: keyword arguments forwarded to airbornegeo.filter_line to low-pass filter the misties along each line (besides data_column and filter_by_column, which are set for you). Must include filter_width; anything else you don’t provide falls back to filter_line’s own defaults (e.g. filter_shape=”gaussian”, engine=”scipy”).lines_to_level (
list[float] |None) – All lines in the network to be levelled together. By default is all lines.intersection_weight_col (
str|None) – Column in inters with per-intersection weights.crossover_error_interp_method (
str) – Method used to fill gaps between misties along a line before filtering (only used when filter_kwargs is given), by default “linear”.relaxation_factor (
float) – Fraction of each line’s fitted mistie trend to remove per iteration, by default 0.5 (i.e. split the mistie evenly between the two lines at each crossover). Values close to 1 correct faster but are more likely to overshoot/oscillate; values closer to 0 converge more slowly but more stably.raise_error_if_unchanged (
bool) – Raise a UserWarning if misties are unchanged from the previous iteration, by default True.max_iterations (
int) – Maximum number of iterations, by default 5. Network levelling generally needs more iterations than pairs levelling since corrections must propagate through the network.rms_tolerance (
float|None) – Convergence criteria, as in crossover_pair_levelling.rms_percent_change_tolerance (
float) – Convergence criteria, as in crossover_pair_levelling.rms_percent_increase_tolerance (
float) – Convergence criteria, as in crossover_pair_levelling.plot_convergence (
bool) – Plot convergence of the levelling corrections.plot_dynamic_convergence (
bool) – Plot convergence of the levelling corrections.progressbar (
bool) – Show a progress bar over iterations.
- Returns:
The levelled dataframe and updated intersections table.
- Return type: