fractopo.analysis package

Submodules

fractopo.analysis.anisotropy module

Anisotropy of connectivity determination utilities.

fractopo.analysis.anisotropy.determine_anisotropy_classification(branch_classification)

Return value based on branch classification.

Only C-C branches have a value, but this can be changed here. Classification can differ from ‘C - C’, ‘C - I’, ‘I - I’ (e.g. ‘C - E’) in which case a value (0) is still returned.

Parameters:: branch_classification (str) – Branch classification string.
Return type:: int
Returns:: Classification encoded as integer.

E.g.

>>> determine_anisotropy_classification("C - C")
1

>>> determine_anisotropy_classification("C - E")
0

fractopo.analysis.anisotropy.determine_anisotropy_sum(azimuth_array, branch_types, length_array, sample_intervals=array([0, 30, 60, 90, 120, 150]))

Determine the sums of branch anisotropies.

Parameters:

azimuth_array (ndarray) – Array of branch azimuth values.
branch_types (ndarray) – Array of branch type classication strings.
length_array (ndarray) – Array of branch lengths.
sample_intervals (ndarray) – Array of the sampling intervals.

Return type:

tuple[ndarray, ndarray]

Returns:

Sums of branch anisotropies.

E.g.

>>> from pprint import pprint
>>> azimuths = np.array([20, 50, 60, 70])
>>> lengths = np.array([2, 5, 6, 7])
>>> branch_types = np.array(["C - C", "C - C", "C - C", "C - I"])
>>> pprint(determine_anisotropy_sum(azimuths, branch_types, lengths))
(array([ 8.09332329, 11.86423103, 12.45612765,  9.71041492,  5.05739707,
        2.15381611]),
 array([  0,  30,  60,  90, 120, 150]))

fractopo.analysis.anisotropy.determine_anisotropy_value(azimuth, branch_type, length, sample_intervals=array([0, 30, 60, 90, 120, 150]))

Calculate anisotropy of connectivity for a branch.

Based on azimuth, branch_type and length. Value is calculated for preset angles (sample_intervals = np.arange(0, 179, 30))

E.g.

Anisotropy for a C-C classified branch:

Return type:: ndarray

>>> determine_anisotropy_value(50, "C - C", 1)
array([0.64278761, 0.93969262, 0.98480775, 0.76604444, 0.34202014,
       0.17364818])

Other classification for branch:

>>> determine_anisotropy_value(50, "C - I", 1)
array([0, 0, 0, 0, 0, 0])

fractopo.analysis.anisotropy.plot_anisotropy_ax(anisotropy_sum, ax, sample_intervals=array([0, 30, 60, 90, 120, 150]))

Plot a styled anisotropy of connectivity to a given PolarAxes.

Spline done with: https://docs.scipy.org/doc/scipy/reference/generated/scipy.interpolate.CubicSpline.html

fractopo.analysis.anisotropy.plot_anisotropy_plot(anisotropy_sum, sample_intervals)

Plot anisotropy values to new figure.

Return type:: tuple[Figure, Axes]

fractopo.analysis.azimuth module

Functions for plotting rose plots.

class fractopo.analysis.azimuth.AzimuthBins(bin_width, bin_locs, bin_heights)

Bases: object

Dataclass for azimuth rose plot bin data.

bin_heights: ndarray

bin_locs: ndarray

bin_width: float

fractopo.analysis.azimuth.decorate_azimuth_ax(ax, label, length_array, set_array, set_names, set_ranges, axial, visualize_sets, append_azimuth_set_text=False, add_abundance_order=False): Decorate azimuth rose plot ax.

fractopo.analysis.azimuth.determine_azimuth_bins(azimuth_array, length_array=None, bin_multiplier=1.0, axial=True)

Calculate azimuth bins for plotting azimuth rose plots.

E.g.

Return type:: AzimuthBins

>>> azimuth_array = np.array([25, 50, 145, 160])
>>> length_array = np.array([5, 5, 10, 60])
>>> azi_bins = determine_azimuth_bins(azimuth_array, length_array)
>>> azi_bins.bin_heights
array([ 5,  5,  0, 70])
>>> azi_bins.bin_locs
array([ 22.5,  67.5, 112.5, 157.5])
>>> azi_bins.bin_width
45.0

fractopo.analysis.azimuth.plot_azimuth_ax(bin_width, bin_locs, bin_heights, bar_color, ax, axial=True)

Plot azimuth rose plot to ax.

Return type:: PolarAxes

fractopo.analysis.azimuth.plot_azimuth_plot(azimuth_array, length_array, azimuth_set_array, azimuth_set_names, azimuth_set_ranges, label, plain, append_azimuth_set_text=False, add_abundance_order=False, axial=True, visualize_sets=False, bar_color='darkgrey')

Plot azimuth rose plot to its own figure.

Returns rose plot bin parameters, figure, ax

Return type:: tuple[AzimuthBins, Figure, PolarAxes]

fractopo.analysis.contour_grid module

Scripts for creating sample grids for fracture trace, branch and node data.

fractopo.analysis.contour_grid.create_grid(cell_width, lines)

Create an empty polygon grid for sampling fracture line data.

Grid is created to always contain all given lines.

E.g.

Return type:: GeoDataFrame

>>> lines = gpd.GeoSeries(
...     [
...         LineString([(1, 1), (2, 2)]),
...         LineString([(2, 2), (3, 3)]),
...         LineString([(3, 0), (2, 2)]),
...         LineString([(2, 2), (-2, 5)]),
...     ]
... )
>>> create_grid(cell_width=0.1, lines=lines).head(5)
                                            geometry
0   POLYGON ((-2 5, -1.9 5, -1.9 4.9, -2 4.9, -2 5))
1  POLYGON ((-2 4.9, -1.9 4.9, -1.9 4.8, -2 4.8, ...
2  POLYGON ((-2 4.8, -1.9 4.8, -1.9 4.7, -2 4.7, ...
3  POLYGON ((-2 4.7, -1.9 4.7, -1.9 4.6, -2 4.6, ...
4  POLYGON ((-2 4.6, -1.9 4.6, -1.9 4.5, -2 4.5, ...

fractopo.analysis.contour_grid.populate_sample_cell(sample_cell, sample_cell_area, traces, nodes, branches, snap_threshold, resolve_branches_and_nodes, traces_sindex=None)

Take a single grid polygon and populate it with parameters.

Mauldon determination requires that E-nodes are defined for every single sample circle. If correct Mauldon values are wanted resolve_branches_and_nodes must be passed as True. This will result in much longer analysis time.

Return type:: dict[str, float]

fractopo.analysis.contour_grid.sample_grid(grid, traces, nodes, branches, snap_threshold, resolve_branches_and_nodes=False)

Populate a sample polygon grid with geometrical and topological parameters.

Return type:: GeoDataFrame

fractopo.analysis.length_distributions module

Utilities for analyzing and plotting length distributions for line data.

class fractopo.analysis.length_distributions.Dist(*values)

Bases: Enum

Enums of powerlaw model types.

EXPONENTIAL = 'exponential'

LOGNORMAL = 'lognormal'

POWERLAW = 'power_law'

TRUNCATED_POWERLAW = 'truncated_power_law'

class fractopo.analysis.length_distributions.LengthDistribution(lengths, area_value, using_branches, name='', _automatic_fit=None)

Bases: object

Dataclass for length distributions.

area_value: float

property automatic_fit: Fit | None: Get automatic powerlaw Fit.

generate_distributions(cut_off=1e-18): Generate ccdf and truncated length data with cut_off.

lengths: ndarray

manual_fit(cut_off): Get manual powerlaw Fit.

name: str = ''

using_branches: bool

class fractopo.analysis.length_distributions.MultiLengthDistribution(distributions, using_branches, fitter=<function numpy_polyfit>, cut_offs=None, _fit_to_multi_scale_lengths=None, _normalized_distributions=None, _optimized=False)

Bases: object

Multi length distribution.

cut_offs: Optional[list[float]] = None

distributions: list[LengthDistribution]

fitter(log_ccm)

Fit numpy polyfit to data.

Return type:: tuple[float, float]

property names: list[str]: Get length distribution names.

normalized_distributions(automatic_cut_offs)

Create normalized and truncated lengths and ccms.

Return type:: tuple[list[ndarray], list[ndarray], list[ndarray], list[ndarray], list[float]]

optimize_cut_offs(shgo_kwargs=None, scorer=<function mean_squared_log_error>)

Get cut-off optimized MultiLengthDistribution.

Return type:: tuple[MultiScaleOptimizationResult, MultiLengthDistribution]

optimized_multi_scale_fit(scorer, shgo_kwargs)

Use scipy.optimize.shgo to optimize fit.

Return type:: MultiScaleOptimizationResult

plot_multi_length_distributions(automatic_cut_offs, plot_truncated_data, scorer=<function mean_squared_log_error>)

Plot multi-scale length distribution.

Return type:: tuple[Polyfit, Figure, Axes]

using_branches: bool

class fractopo.analysis.length_distributions.MultiScaleOptimizationResult(polyfit: Polyfit, cut_offs: ndarray, optimize_result: OptimizeResult, x0: ndarray, bounds: ndarray, proportions_of_data: list[float])

Bases: NamedTuple

Results of scipy.optimize.shgo on length data.

bounds: ndarray: Alias for field number 4

cut_offs: ndarray: Alias for field number 1

optimize_result: OptimizeResult: Alias for field number 2

polyfit: Polyfit: Alias for field number 0

proportions_of_data: list[float]: Alias for field number 5

x0: ndarray: Alias for field number 3

class fractopo.analysis.length_distributions.Polyfit(y_fit: ndarray, m_value: float, constant: float, score: float, scorer: Callable[[ndarray, ndarray], float])

Bases: NamedTuple

Results of a polyfit to length data.

constant: float: Alias for field number 2

m_value: float: Alias for field number 1

score: float: Alias for field number 3

scorer: Callable[[ndarray, ndarray], float]: Alias for field number 4

y_fit: ndarray: Alias for field number 0

class fractopo.analysis.length_distributions.SilentFit(data, discrete=False, xmin=None, xmax=None, verbose=True, fit_method='Likelihood', estimate_discrete=True, discrete_approximation='round', sigma_threshold=None, parameter_range=None, fit_optimizer=None, xmin_distance='D', xmin_distribution='power_law', **kwargs)

Bases: Fit

Wrap powerlaw.Fit for the singular purpose of silencing output.

Silences output both to stdout and stderr.

fractopo.analysis.length_distributions.all_fit_attributes_dict(fit)

Collect ‘all’ fit attributes into a dict.

Return type:: dict[str, float]

fractopo.analysis.length_distributions.apply_cut_off(lengths, ccm, cut_off=1e-18)

Apply cut-off to length data and associated ccm.

Return type:: tuple[ndarray, ndarray]

>>> lengths = np.array([2, 4, 8, 16, 32])
>>> ccm = np.array([1. , 0.8, 0.6, 0.4, 0.2])
>>> cut_off = 4.5
>>> apply_cut_off(lengths, ccm, cut_off)
(array([ 8, 16, 32]), array([0.6, 0.4, 0.2]))

fractopo.analysis.length_distributions.calculate_critical_distance_value(data_length, data_length_minimum=51)

Calculate approximate critical distance value for large (n>50) sample counts.

Assumes significance level of 0.05. If the Kolmogorov-Smirnov distance value is smaller than the critical value, the null hypothesis, i.e., that the distributions are the same, is accepted but not verified.

fractopo.analysis.length_distributions.calculate_exponent(alpha): Calculate exponent from powerlaw.alpha.

fractopo.analysis.length_distributions.calculate_fitted_values(log_lengths, m_value, constant)

Calculate fitted values of y.

Return type:: ndarray

fractopo.analysis.length_distributions.cut_off_proportion_of_data(fit, length_array)

Get the proportion of data cut off by powerlaw cut off.

If no fit is passed the cut off is the one used in automatic_fit.

Return type:: float

fractopo.analysis.length_distributions.describe_powerlaw_fit(fit, length_array, label=None)

Compose dict of fit powerlaw attributes and comparisons between fits.

Return type:: dict[str, float]

fractopo.analysis.length_distributions.distribution_compare_dict(fit)

Compose a dict of length distribution fit comparisons.

Return type:: dict[str, float]

fractopo.analysis.length_distributions.fit_to_multi_scale_lengths(ccm, lengths, fitter=<function numpy_polyfit>, scorer=<function mean_squared_log_error>)

Fit np.polyfit to multiscale length distributions.

Returns the fitted values, exponent and constant of fit within a Polyfit instance.

Return type:: Polyfit

fractopo.analysis.length_distributions.numpy_polyfit(log_lengths, log_ccm)

Fit numpy polyfit to data.

Return type:: tuple[float, float]

fractopo.analysis.length_distributions.optimize_cut_offs(cut_offs, distributions, fitter, scorer, *_)

Optimize multiscale fit.

Requirements for the optimization function are that the function must take one argument of 1-d array and return a single float. It can take static arguments (distributions, fitter).

Return type:: float

fractopo.analysis.length_distributions.plot_distribution_fits(length_array, label, using_branches, use_probability_density_function, cut_off=None, fit=None, fig=None, ax=None, fits_to_plot=(Dist.POWERLAW, Dist.LOGNORMAL, Dist.EXPONENTIAL), plain=False)

Plot length distribution and powerlaw fits.

If a powerlaw.Fit is not given it will be automatically determined (using the optionally given cut_off).

Return type:: tuple[Optional[Fit], Figure, Axes]

fractopo.analysis.length_distributions.plot_fit_on_ax(ax, fit, fit_distribution, use_probability_density_function)

Plot powerlaw model to ax.

Return type:: None

fractopo.analysis.length_distributions.plot_multi_distributions_and_fit(truncated_length_array_all, ccm_array_normed_all, full_length_array_all, full_ccm_array_normed_all, cut_offs, names, polyfit, using_branches, plot_truncated_data)

Plot multi-scale length distribution.

Return type:: tuple[Figure, Axes]

fractopo.analysis.length_distributions.scikit_linear_regression(log_lengths, log_ccm)

Fit using scikit LinearRegression.

Return type:: tuple[float, float]

fractopo.analysis.length_distributions.setup_ax_for_ld(ax, using_branches, indiv_fit, use_probability_density_function, plain=False)

Configure ax for length distribution plots.

Parameters:

ax (Axes) – Ax to setup.
using_branches (bool) – Are the lines in the axis branches or traces.
indiv_fit (bool) – Is the plot single-scale or multi-scale.
use_probability_density_function (bool) – Whether to use complementary cumulative distribution function
plain (bool) – Should the stylizing be kept to a minimum.

fractopo.analysis.length_distributions.setup_length_dist_legend(ax)

Set up legend for length distribution plots.

Used for both single and multi distribution plots.

fractopo.analysis.length_distributions.sort_and_log_lengths_and_ccm(lengths, ccm)

Preprocess lengths and ccm.

Sorts them and calculates their natural logarithmic.

Return type:: tuple[ndarray, ndarray]

fractopo.analysis.length_distributions.sorted_lengths_and_ccm(lengths, area_value)

Get (normalized) complementary cumulative number array.

Give area_value as None to not normalize.

Return type:: tuple[ndarray, ndarray]

>>> lengths = np.array([2, 4, 8, 16, 32])
>>> area_value = 10.0
>>> sorted_lengths_and_ccm(lengths, area_value)
(array([ 2,  4,  8, 16, 32]), array([0.1 , 0.08, 0.06, 0.04, 0.02]))

>>> lengths = np.array([2, 4, 8, 16, 32])
>>> area_value = None
>>> sorted_lengths_and_ccm(lengths, area_value)
(array([ 2,  4,  8, 16, 32]), array([1. , 0.8, 0.6, 0.4, 0.2]))

fractopo.analysis.line_data module

Trace and branch data analysis with LineData class abstraction.

class fractopo.analysis.line_data.LineData(_line_gdf, using_branches, azimuth_set_ranges, azimuth_set_names, length_set_ranges=(), length_set_names=(), area_boundary_intersects=<factory>, _automatic_fit=None)

Bases: object

Wrapper around the given GeoDataFrame with trace or branch data.

The line_gdf reference is passed and LineData will modify the input line_gdf instead of copying the input frame. This means line_gdf columns are accessible in the passed input reference upstream.

area_boundary_intersects: ndarray

property automatic_fit: Fit | None: Get automatic powerlaw Fit.

property azimuth_array: ndarray: Array of trace or branch azimuths.

property azimuth_set_array: ndarray: Array of trace or branch azimuth set ids.

property azimuth_set_counts: dict[str, int]: Get dictionary of azimuth set counts.

property azimuth_set_length_arrays: dict[str, ndarray]: Get length arrays of each azimuth set.

azimuth_set_names: Sequence[str]

azimuth_set_ranges: Sequence[tuple[Union[float, int, Real], Union[float, int, Real]]]

property boundary_intersect_count: dict[str, int]: Get counts of line intersects with boundary.

boundary_intersect_count_desc(label)

Get counts of line intersects with boundary.

Return type:: dict[str, int]

describe_fit(label=None, cut_off=None): Return short description of automatic powerlaw fit.

determine_manual_fit(cut_off)

Get manually determined Fit with set cut off.

Return type:: Optional[Fit]

property geometry: GeoSeries: Get line geometries.

property length_array: ndarray

Array of trace or branch lengths.

Note: lengths can be 0.0 due to boundary weighting.

property length_array_non_weighted: ndarray: Array of trace or branch lengths not weighted by boundary conditions.

property length_boundary_weights: Array of weights for lines based on intersection count with boundary.

property length_set_array: ndarray: Array of trace or branch length set ids.

property length_set_counts: dict[str, int]: Get dictionary of length set counts.

length_set_names: Sequence[str] = ()

length_set_ranges: Sequence[tuple[Union[float, int, Real], Union[float, int, Real]]] = ()

plot_azimuth(label, append_azimuth_set_text=False, add_abundance_order=False, visualize_sets=False, bar_color='darkgrey', plain=False)

Plot azimuth data in rose plot.

Return type:: tuple[AzimuthBins, Figure, PolarAxes]

plot_azimuth_set_count(label)

Plot azimuth set counts.

Return type:: tuple[Figure, Axes]

plot_azimuth_set_lengths(use_probability_density_function=False)

Plot azimuth set length distributions with fits.

Return type:: tuple[list[Optional[Fit]], list[Figure], list[Axes]]

plot_length_set_count(label)

Plot length set counts.

Return type:: tuple[Figure, Axes]

plot_lengths(label, use_probability_density_function, fit=None, plain=False, fits_to_plot=(Dist.POWERLAW, Dist.LOGNORMAL, Dist.EXPONENTIAL))

Plot length data with powerlaw fit.

Return type:: tuple[Optional[Fit], Figure, Axes]

using_branches: bool

fractopo.analysis.multi_network module

MultiNetwork implementation for handling multiple network analysis.

class fractopo.analysis.multi_network.MultiNetwork(networks: tuple[Network, ...])

Bases: NamedTuple

Multiple Network analysis.

basic_network_descriptions_df(columns)

Create DataFrame useful for basic Network characterization.

columns should contain key value pairs where the key is the column name in numerical_network_description dict. Value is a tuple where the first member is a new name for the column or alternatively None in which case the column name isn’t changed. The second member should be the type of the column, typically either str, int or float.

collective_azimuth_sets()

Get collective azimuth set names.

Checks that all Networks have the same azimuth sets.

Return type:: tuple[tuple[str, ...], Sequence[tuple[Union[float, int, Real], Union[float, int, Real]]]]

multi_length_distributions(using_branches)

Get MultiLengthDistribution of all networks.

Return type:: MultiLengthDistribution

network_length_distributions(using_branches, using_azimuth_sets)

Get length distributions of Networks.

Return type:: dict[str, dict[str, LengthDistribution]]

networks: tuple[Network, ...]: Alias for field number 0

plot_branch(colors=None): Plot multi-network ternary branch type plot.

plot_branch_azimuth_set_lengths(automatic_cut_offs, plot_truncated_data)

Plot multi-network trace azimuths set lengths with fits.

Return type:: tuple[dict[str, MultiLengthDistribution], list[Polyfit], list[Figure], list[Axes]]

plot_multi_length_distribution(using_branches, automatic_cut_offs, plot_truncated_data, multi_distribution=None)

Plot multi-length distribution fit.

Use multi_length_distributions() to get most parameters used in fitting the multi-scale distribution.

Return type:: tuple[MultiLengthDistribution, Polyfit, Figure, Axes]

plot_trace_azimuth_set_lengths(automatic_cut_offs, plot_truncated_data)

Plot multi-network trace azimuths set lengths with fits.

Return type:: tuple[dict[str, MultiLengthDistribution], list[Polyfit], list[Figure], list[Axes]]

plot_xyi(colors=None): Plot multi-network ternary XYI plot.

set_multi_length_distributions(using_branches)

Get set-wise multi-length distributions.

Return type:: dict[str, MultiLengthDistribution]

subsample(min_radii, random_choice=RandomChoice.radius, samples=1)

Subsample all Networks in MultiNetwork.

Parameters:

min_radii (Union[float, dict[str, float]]) – The minimum radius for subsamples can be either given as static or as a mapping that maps network names to specific radii.
random_choice (RandomChoice) – Whether to use radius or area as the random choice parameter.
samples (int) – How many subsamples to conduct per network.

Return type:

list[Optional[dict[str, Union[float, int, Real, str]]]]

Returns:

Subsamples

fractopo.analysis.network module

Analyse and plot trace map data with Network.

class fractopo.analysis.network.Network(trace_gdf, area_gdf, name='Network', determine_branches_nodes=False, snap_threshold=0.001, truncate_traces=True, circular_target_area=False, azimuth_set_names=('1', '2', '3'), azimuth_set_ranges=((0, 60), (60, 120), (120, 180)), trace_length_set_names=(), trace_length_set_ranges=(), branch_length_set_names=(), branch_length_set_ranges=(), branch_gdf=<factory>, node_gdf=<factory>, censoring_area=<factory>, cache_results=True, remove_z_coordinates_from_inputs=True, _anisotropy=None, _parameters=None, _azimuth_set_relationships=None, _trace_length_set_relationships=None, _trace_intersects_target_area_boundary=None, _branch_intersects_target_area_boundary=None)

Bases: object

Trace network.

Consists of at its simplest of validated traces and a target area that delineates the traces i.e., only trace_gdf and area_gdf parameters are required to run the network analysis but results might not be correct or match your expectations e.g., traces are truncated to target area by default.

Parameters:

trace_gdf (GeoDataFrame) – GeoDataFrame containing trace data i.e. shapely.geometry.LineString geometries.
area_gdf (GeoDataFrame) – GeoDataFrame containing target area data i.e. (Multi)Polygon's.
name (str) – Name the Network.
determine_branches_nodes (bool) – Whether to determine branches and nodes.
snap_threshold (float) – The snapping distance threshold to identify snapped traces.
truncate_traces (bool) – Whether to crop the traces at the target area boundary.
circular_target_area (bool) – Is the target are a circle.
azimuth_set_names (Sequence[str]) – Names of each azimuth set.
azimuth_set_ranges (Sequence[tuple[Union[float, int, Real], Union[float, int, Real]]]) – Ranges of each azimuth set.
trace_length_set_names (Sequence[str]) – Names of each trace length set.
trace_length_set_ranges (Sequence[tuple[Union[float, int, Real], Union[float, int, Real]]]) – Ranges of each trace length set.
branch_length_set_names (Sequence[str]) – Names of each branch length set.
branch_length_set_ranges (Sequence[tuple[Union[float, int, Real], Union[float, int, Real]]]) – Ranges of each branch length set.
branch_gdf (GeoDataFrame) – GeoDataFrame containing branch data. It is recommended to let fractopo.Network determine both branches and nodes instead of passing them here.
node_gdf (GeoDataFrame) – GeoDataFrame containing node data. It is recommended to let fractopo.Network determine both branches and nodes instead of passing them here.
censoring_area (GeoDataFrame) – Polygon(s) in GeoDataFrame that delineate(s) the area in which trace digitization was uncertain due to censoring caused by e.g. vegetation.
cache_results (bool) – Whether to use joblib memoize to disk-cache computationally expensive results.

property anisotropy: Tuple[ndarray, ndarray]: Determine anisotropy of connectivity.

area_gdf: GeoDataFrame

assign_branches_nodes(branches=None, nodes=None): Determine and assign branches and nodes as attributes.

azimuth_set_names: Sequence[str] = ('1', '2', '3')

azimuth_set_ranges: Sequence[tuple[Union[float, int, Real], Union[float, int, Real]]] = ((0, 60), (60, 120), (120, 180))

property azimuth_set_relationships: DataFrame: Determine azimuth set relationships.

property branch_azimuth_array: ndarray: Get branch azimuths as array.

property branch_azimuth_set_array: ndarray: Get azimuth set for each branch.

property branch_azimuth_set_counts: Dict[str, int]: Get branch azimuth set counts.

property branch_counts: Dict[str, int]: Get branch counts.

branch_gdf: GeoDataFrame

property branch_intersects_target_area_boundary: ndarray: Get array of E-component count.

property branch_length_array: ndarray: Get branch lengths as array.

property branch_length_array_non_weighted: ndarray: Get non-boundary-weighted branch lengths as array.

branch_length_distribution(azimuth_set)

Create structured LengthDistribution instance of branch length data.

Return type:: LengthDistribution

property branch_length_set_array: ndarray: Get length set for each branch.

property branch_length_set_counts: Dict[str, int]: Get branch length set counts.

branch_length_set_names: Sequence[str] = ()

branch_length_set_ranges: Sequence[tuple[Union[float, int, Real], Union[float, int, Real]]] = ()

branch_lengths_powerlaw_fit(cut_off=None)

Determine powerlaw fit for branch lengths.

Return type:: Optional[Fit]

property branch_lengths_powerlaw_fit_description: Dict[str, float]: Short numerical description dict of branch length powerlaw fit.

property branch_series: GeoSeries: Get branch geometries as GeoSeries.

property branch_types: ndarray: Get branch type of each branch.

cache_results: bool = True

censoring_area: GeoDataFrame

circular_target_area: bool = False

contour_grid(cell_width=None, bounds_divider=20.0, precursor_grid=None, resolve_branches_nodes=False)

Sample the network with a contour grid.

If cell_width is passed it is used as the cell width. Otherwise a cell width is calculated using the network branch bounds using the passed bounds_divider or its default value.

If precursor_grid is passed it is used as the grid in which each Polygon cell is filled with calculated network parameter values.

determine_branches_nodes: bool = False

estimate_censoring()

Estimate the amount of censoring as area float value.

Censoring is caused by e.g. vegetation.

Returns np.nan if no censoring_area is passed by the user into Network creation or if the passed GeoDataFrame is empty.

Return type:: float

export_network_analysis(output_path, include_contour_grid=True, contour_grid_cell_size=None, fits_to_plot=(Dist.EXPONENTIAL, Dist.LOGNORMAL, Dist.POWERLAW))

Export pre-selected Network analysis results to a directory.

The chosen analyses are opionated but should contain at least the basic results of fracture network analysis.

output_path should correspond to a path to an existing or directory or direct path to a non-existing directory where one will be created.

export_network_analysis_topology(save_fig_to_export_path, write_geodataframe_to_export_path, include_contour_grid, contour_grid_cell_size, fits_to_plot): Export topological network analysis results.

property length_set_relationships: DataFrame: Determine length set relationships.

name: str = 'Network'

property node_counts: Dict[str, int]: Get node counts.

node_gdf: GeoDataFrame

property node_series: GeoSeries: Get node geometries as GeoSeries.

property node_types: ndarray: Get node type of each node.

numerical_network_description(trace_lengths_cut_off=None, branch_lengths_cut_off=None)

Collect numerical network attributes and return them as a dictionary.

Return type:: Dict[str, Union[float, int, Real, str]]

property parameters: Dict[str, float]: Get numerical geometric and topological parameters.

property plain_name: Get filename friendly name for Network based on name attribute.

plot_anisotropy(label=None, color=None)

Plot anisotropy of connectivity plot.

Return type:: Optional[Tuple[Figure, Axes]]

plot_azimuth_crosscut_abutting_relationships()

Plot azimuth set crosscutting and abutting relationships.

Return type:: Tuple[List[Figure], List[ndarray]]

plot_branch(label=None)

Plot ternary plot of branch types.

Return type:: Tuple[Figure, Axes, TernaryAxesSubplot]

plot_branch_azimuth(label=None, append_azimuth_set_text=False, add_abundance_order=False, visualize_sets=False, bar_color='darkgrey', plain=False)

Plot branch azimuth rose plot.

Return type:: Tuple[AzimuthBins, Figure, PolarAxes]

plot_branch_azimuth_set_count(label=None)

Plot branch azimuth set counts.

Return type:: Tuple[Figure, Axes]

plot_branch_azimuth_set_lengths()

Plot branch azimuth set lengths with fits.

Return type:: Tuple[List[Optional[Fit]], List[Figure], List[Axes]]

plot_branch_length_set_count(label=None)

Plot branch length set counts.

Return type:: Tuple[Figure, Axes]

plot_branch_lengths(label=None, fit=None, use_probability_density_function=False, plain=False, fits_to_plot=(Dist.POWERLAW, Dist.LOGNORMAL, Dist.EXPONENTIAL))

Plot branch length distribution with powerlaw fits.

Return type:: Tuple[Optional[Fit], Figure, Axes]

plot_contour(parameter, sampled_grid)

Plot contour plot of a geometric or topological parameter.

Creating the contour grid is expensive so the sampled_grid must be first created with Network.contour_grid method and then passed to this one for plotting.

Return type:: Tuple[Figure, Axes]

plot_parameters(label=None, color=None)

Plot geometric and topological parameters.

Return type:: Optional[Tuple[Figure, Axes]]

plot_trace_azimuth(label=None, append_azimuth_set_text=False, add_abundance_order=False, visualize_sets=False, bar_color='darkgrey', plain=False)

Plot trace azimuth rose plot.

Return type:: Tuple[AzimuthBins, Figure, PolarAxes]

plot_trace_azimuth_set_count(label=None)

Plot trace azimuth set counts.

Return type:: Tuple[Figure, Axes]

plot_trace_azimuth_set_lengths()

Plot trace azimuth set lengths with fits.

Return type:: Tuple[List[Optional[Fit]], List[Figure], List[Axes]]

plot_trace_length_crosscut_abutting_relationships()

Plot length set crosscutting and abutting relationships.

Return type:: Tuple[List[Figure], List[ndarray]]

plot_trace_length_set_count(label=None)

Plot trace length set counts.

Return type:: Tuple[Figure, Axes]

plot_trace_lengths(label=None, fit=None, use_probability_density_function=False, plain=False, fits_to_plot=(Dist.POWERLAW, Dist.LOGNORMAL, Dist.EXPONENTIAL))

Plot trace length distribution with powerlaw fits.

Return type:: Tuple[Optional[Fit], Figure, Axes]

plot_xyi(label=None)

Plot ternary plot of node types.

Return type:: Tuple[Figure, Axes, TernaryAxesSubplot]

remove_z_coordinates_from_inputs: bool = True

representative_points()

Get representative point(s) of target area(s).

Return type:: List[Point]

reset_length_data()

Reset LineData attributes.

WARNING: Mostly untested.

snap_threshold: float = 0.001

property target_areas: List[Polygon | MultiPolygon]: Get all target areas from area_gdf.

property total_area: float: Get total area.

property trace_azimuth_array: ndarray: Get trace azimuths as array.

property trace_azimuth_set_array: ndarray: Get azimuth set for each trace.

property trace_azimuth_set_counts: Dict[str, int]: Get trace azimuth set counts.

trace_gdf: GeoDataFrame

property trace_intersects_target_area_boundary: ndarray

Check traces for intersection with target area boundaries.

Results are in integers:

0 == No intersections
1 == One intersection
2 == Two intersections

Does not discriminate between which target area (if multiple) the trace intersects. Intersection detection based on snap_threshold.

property trace_length_array: ndarray: Get trace lengths as array.

property trace_length_array_non_weighted: ndarray: Get non-boundary-weighted trace lengths as array.

trace_length_distribution(azimuth_set)

Create structured LengthDistribution instance of trace length data.

Return type:: LengthDistribution

property trace_length_set_array: ndarray: Get length set for each trace.

property trace_length_set_counts: Dict[str, int]: Get trace length set counts.

trace_length_set_names: Sequence[str] = ()

trace_length_set_ranges: Sequence[tuple[Union[float, int, Real], Union[float, int, Real]]] = ()

trace_lengths_powerlaw_fit(cut_off=None)

Determine powerlaw fit for trace lengths.

Return type:: Optional[Fit]

property trace_lengths_powerlaw_fit_description: Dict[str, float]: Short numerical description dict of trace length powerlaw fit.

property trace_series: GeoSeries: Get trace geometries as GeoSeries.

truncate_traces: bool = True

write_branches_and_nodes(output_dir_path, branches_name=None, nodes_name=None)

Write branches and nodes to disk.

Enables reuse of the same data in analysis of the same data to skip topology determination which is computationally expensive.

Writes only with the GeoJSON driver as there are differences between different spatial filetypes. Only GeoJSON is supported to avoid unexpected errors.

fractopo.analysis.network.requires_topology(func)

Wrap methods that require determined topology.

Raises an error if trying to call them without determined topology.

Return type:: Callable

fractopo.analysis.parameters module

Analysis and plotting of geometric and topological parameters.

fractopo.analysis.parameters.branches_intersect_boundary(branch_types)

Get array of if branches have E-component (intersects target area).

Return type:: ndarray

fractopo.analysis.parameters.convert_counts(counts)

Convert float and int value in counts to ints only.

Used by branches and nodes count calculators.

Return type:: dict[str, int]

fractopo.analysis.parameters.counts_to_point(counts, is_nodes, scale=100)

Create ternary point from node_counts.

The order is important: for nodes: X, I, Y and for branches: CC, II, CI.

Return type:: Optional[tuple[float, float, float]]

fractopo.analysis.parameters.decorate_branch_ax(ax, tax, counts): Decorate ternary branch plot.

fractopo.analysis.parameters.decorate_count_ax(ax, tax, label_counts, is_nodes): Decorate ternary count plot.

fractopo.analysis.parameters.decorate_xyi_ax(ax, tax, counts): Decorate xyi plot.

fractopo.analysis.parameters.determine_branch_type_counts(branch_types, branches_defined)

Determine branch type counts.

Return type:: dict[str, Union[float, int, Real]]

fractopo.analysis.parameters.determine_node_type_counts(node_types, branches_defined)

Determine node type counts.

Return type:: dict[str, Union[float, int, Real]]

fractopo.analysis.parameters.determine_set_counts(set_names, set_array)

Determine counts in for each set.

Return type:: dict[str, int]

fractopo.analysis.parameters.determine_topology_parameters(trace_length_array, area, branches_defined, correct_mauldon, node_counts, branch_length_array)

Determine geometric (and topological) parameters.

Number of traces (and branches) are determined by node counting.

The passed trace_length_array should be non-weighted.

Return type:: dict[str, float]

fractopo.analysis.parameters.initialize_ternary_ax(ax, tax)

Decorate ternary ax for both XYI and branch types.

Returns a font dict for use in plotting text.

Return type:: dict

fractopo.analysis.parameters.initialize_ternary_branches_points(ax, tax): Initialize ternary branches plot ax and tax.

fractopo.analysis.parameters.initialize_ternary_points(ax, tax): Initialize ternary points figure ax and tax.

fractopo.analysis.parameters.plot_branch_plot_ax(counts, label, tax, color=None): Plot ternary branch plot to tax.

fractopo.analysis.parameters.plot_parameters_plot(topology_parameters_list, labels, colors=None): Plot topological parameters.

fractopo.analysis.parameters.plot_set_count(set_counts, label)

Plot set counts.

Return type:: tuple[Figure, Axes]

fractopo.analysis.parameters.plot_ternary_plot(counts_list, labels, is_nodes, colors=None)

Plot ternary plot.

Same function is used to plot both XYI and branch type ternary plots.

Return type:: tuple[Figure, Axes, TernaryAxesSubplot]

fractopo.analysis.parameters.plot_xyi_plot_ax(counts, label, tax, color=None): Plot XYI pointst to given ternary axis (tax).

fractopo.analysis.parameters.tern_plot_branch_lines(tax)

Plot line of random assignment of nodes to branches to a branch ternary tax.

Line positions taken from NetworkGT open source code. Credit to: https://github.com/BjornNyberg/NetworkGT

Parameters:: tax (ternary.TernaryAxesSubplot) – Ternary axis to plot to

fractopo.analysis.parameters.tern_plot_the_fing_lines(tax, cs_locs=(1.3, 1.5, 1.7, 1.9))

Plot connections per branch parameter to XYI-plot.

If not using the pre-determined locations the texts will not be correctly placed as they use absolute positions and labels.

Parameters:

tax (TernaryAxesSubplot) – Ternary axis to plot to.
cs_locs (tuple[float, ...]) – Pre-determined locations for the lines.

fractopo.analysis.parameters.tern_yi_func(c, x)

Plot Connections per branch threshold line to branch ternary plot.

Uses absolute values.

fractopo.analysis.parameters.ternary_heatmapping(x_values, y_values, i_values, number_of_bins, scale_divider=1.0, ax=None)

Plot ternary heatmap.

Modified from: https://github.com/marcharper/python-ternary/issues/81

Return type:: tuple[Figure, TernaryAxesSubplot]

fractopo.analysis.parameters.ternary_point_kwargs(alpha=1.0, zorder=4, s=25, marker='X'): Plot point to a ternary figure.

fractopo.analysis.parameters.ternary_text(text, ax): Add ternary text about counts.

fractopo.analysis.random_sampling module

Utilities for randomly Network sampling traces.

class fractopo.analysis.random_sampling.NetworkRandomSampler(trace_gdf, area_gdf, min_radius, snap_threshold, random_choice, name)

Bases: object

Randomly sample traces inside given target area.

area_gdf: GeoDataFrame

static area_gdf_should_contain_polygon(area_gdf)

Check that area_gdf contains one Polygon.

Return type:: GeoDataFrame

property max_area: float: Calculate maximum area from max_radius.

property max_radius: float: Calculate max radius from given area_gdf.

property min_area: float: Calculate minimum area from min_radius.

min_radius: float

name: str

random_area()

Calculate random area in area range.

Range is calculated from [min_radius, max_radius[.

Return type:: float

random_choice: Union[RandomChoice, str]

static random_choice_should_be_enum(random_choice)

Check that random_choice is valid.

Return type:: RandomChoice

random_network_sample(determine_branches_nodes=True)

Get random Network sample with a random target area.

Returns the network, the sample circle centroid and circle radius.

Return type:: RandomSample

classmethod random_network_sampler(cls, network, min_radius, random_choice=RandomChoice.radius)

Initialize NetworkRandomSampler for random sampling.

Assumes that Network target area is a single Polygon circle.

random_radius()

Calculate random radius in range [min_radius, max_radius[.

Return type:: float

random_target_circle()

Get random target area and its centroid and radius.

The target area is always within the original target area.

Return type:: tuple[Polygon, Point, float]

snap_threshold: float

property target_area_centroid: Point: Get target area centroid.

property target_circle: Polygon: Target circle Polygon from area_gdf.

trace_gdf: GeoDataFrame

static trace_gdf_should_contain_traces(trace_gdf)

Check that trace_gdf contains LineString traces.

Return type:: GeoDataFrame

static value_should_be_positive(min_radius)

Check that value is positive.

Return type:: Union[float, int, Real]

class fractopo.analysis.random_sampling.RandomChoice(*values)

Bases: Enum

Choose between random area or radius.

The choice is relevant because area is polynomially correlated with radius.

area = 'area'

radius = 'radius'

class fractopo.analysis.random_sampling.RandomSample(network_maybe, target_centroid, radius, name)

Bases: object

Dataclass for sampling results.

name: str

network_maybe: Optional[Network]

radius: float

target_centroid: Point

fractopo.analysis.relationships module

Functions for plotting cross-cutting and abutting relationships.

fractopo.analysis.relationships.determine_crosscut_abutting_relationships(trace_series, node_series, node_types, set_array, set_names, buffer_value, label)

Determine cross-cutting and abutting relationships between trace sets.

Determines relationships between all inputted sets by using spatial intersects between node and trace data.

E.g.

Return type:: DataFrame

>>> trace_series = gpd.GeoSeries(
...     [LineString([(0, 0), (1, 0)]), LineString([(0, 1), (0, -1)])]
... )
>>> node_series = gpd.GeoSeries(
...     [Point(0, 0), Point(1, 0), Point(0, 1), Point(0, -1)]
... )
>>> node_types = np.array(["Y", "I", "I", "I"])
>>> set_array = np.array(["1", "2"])
>>> set_names = ("1", "2")
>>> buffer_value = 0.001
>>> label = "title"
>>> determine_crosscut_abutting_relationships(
...     trace_series,
...     node_series,
...     node_types,
...     set_array,
...     set_names,
...     buffer_value,
...     label,
... )
    name    sets  x  y y-reverse error-count
0  title  (1, 2)  0  1         0           0

TODO: No within set relations…..yet… Problem?

fractopo.analysis.relationships.determine_intersect(node, node_class, l1, l2, first_set, second_set, first_setpointtree, buffer_value)

Determine what intersection the node represents.

TODO: R0912: Too many branches.

Return type:: dict[str, Union[Point, str, tuple[str, str], bool]]

fractopo.analysis.relationships.determine_intersects(trace_series_two_sets, set_names_two_sets, node_series_xy_intersects, node_types_xy_intersects, buffer_value)

Determine how abutments and crosscuts occur between two sets.

E.g.

Return type:: DataFrame

>>> traces = gpd.GeoSeries([LineString([(0, 0), (1, 1)])]), gpd.GeoSeries(
...     [LineString([(0, 1), (0, -1)])]
... )
>>> set_names_two_sets = ("1", "2")
>>> node_series_xy_intersects = gpd.GeoSeries([Point(0, 0)])
>>> node_types_xy_intersects = np.array(["Y"])
>>> buffer_value = 0.001
>>> determine_intersects(
...     traces,
...     set_names_two_sets,
...     node_series_xy_intersects,
...     node_types_xy_intersects,
...     buffer_value,
... )
          node nodeclass    sets  error
0  POINT (0 0)         Y  (1, 2)  False

fractopo.analysis.relationships.determine_nodes_intersecting_sets(trace_series_two_sets, set_names_two_sets, node_series_xy, buffer_value)

Conduct a spatial intersect between nodes and traces.

Node GeoDataFrame contains only X- and Y-nodes and the trace GeoDataFrame only two sets. Returns boolean array of based on intersections.

E.g.

Return type:: list[bool]

>>> traces = gpd.GeoSeries([LineString([(0, 0), (1, 1)])]), gpd.GeoSeries(
...     [LineString([(0, 1), (0, -1)])]
... )
>>> set_names_two_sets = ("1", "2")
>>> nodes_xy = gpd.GeoSeries([Point(0, 0), Point(1, 1), Point(0, 1), Point(0, -1)])
>>> buffer_value = 0.001
>>> determine_nodes_intersecting_sets(
...     traces, set_names_two_sets, nodes_xy, buffer_value
... )
[True, False, False, False]

fractopo.analysis.relationships.plot_crosscut_abutting_relationships_plot(relations_df, set_array, set_names)

Plot cross-cutting and abutting relationships.

Return type:: tuple[list[Figure], list[ndarray]]

fractopo.analysis.subsampling module

Utilities for Network subsampling.

fractopo.analysis.subsampling.aggregate_chosen(chosen, default_aggregator=<function mean_aggregation>)

Aggregate a collection of subsampled circles for params.

Weights averages by the area of each subsampled circle.

Return type:: dict[str, Any]

fractopo.analysis.subsampling.area_weighted_index_choice(idxs, areas, compressor)

Make area-weighted choce from list of indexes.

Return type:: int

fractopo.analysis.subsampling.choose_sample_from_group(group)

Choose single sample from group DataFrame.

Return type:: dict[str, Union[float, int, Real, str]]

fractopo.analysis.subsampling.collect_indexes_of_base_circles(idxs, how_many, areas)

Collect indexes of base circles, area-weighted and randomly.

Return type:: list[int]

fractopo.analysis.subsampling.create_sample(sampler)

Sample with NetworkRandomSampler and return Network description.

Return type:: Optional[dict[str, Union[float, int, Real, str]]]

fractopo.analysis.subsampling.gather_subsample_descriptions(subsample_results)

Gather results from a list of subsampling ProcessResults.

Return type:: list[dict[str, Union[float, int, Real, str]]]

fractopo.analysis.subsampling.group_gathered_subsamples(subsamples, groupby_column='Name')

Group gathered subsamples.

By default groups by Name column.

Return type:: dict[str, list[dict[str, Union[float, int, Real, str]]]]

>>> subsamples = [
...     {"param": 2.0, "Name": "myname"},
...     {"param": 2.0, "Name": "myname"},
... ]
>>> group_gathered_subsamples(subsamples)
{'myname': [{'param': 2.0, 'Name': 'myname'}, {'param': 2.0, 'Name': 'myname'}]}

fractopo.analysis.subsampling.groupby_keyfunc(item, groupby_column='Name')

Use groupby_column to group values.

Return type:: str

fractopo.analysis.subsampling.random_sample_of_circles(grouped, circle_names_with_diameter, min_circles=1, max_circles=None)

Get a random sample of circles from grouped subsampled data.

Both the amount of overall circles and which circles within each group is random. Data is grouped by target area name.

Return type:: list[dict[str, Union[float, int, Real, str]]]

fractopo.analysis.subsampling.subsample_networks(networks, min_radii, random_choice=RandomChoice.radius, samples=1)

Subsample given Sequence of Networks.

Return type:: list[Optional[dict[str, Union[float, int, Real, str]]]]

Module contents

Contains most analysis utilities and abstractions.