fractopo.analysis.network module

Analyse and plot trace map data with Network.

class fractopo.analysis.network.Network(trace_gdf: ~geopandas.geodataframe.GeoDataFrame, area_gdf: ~geopandas.geodataframe.GeoDataFrame, name: str = 'Network', determine_branches_nodes: bool = False, snap_threshold: float = 0.001, truncate_traces: bool = True, circular_target_area: bool = False, azimuth_set_names: ~typing.Sequence[str] = ('1', '2', '3'), azimuth_set_ranges: ~collections.abc.Sequence[tuple[float | int | ~numbers.Real, float | int | ~numbers.Real]] = ((0, 60), (60, 120), (120, 180)), trace_length_set_names: ~typing.Sequence[str] = (), trace_length_set_ranges: ~collections.abc.Sequence[tuple[float | int | ~numbers.Real, float | int | ~numbers.Real]] = (), branch_length_set_names: ~typing.Sequence[str] = (), branch_length_set_ranges: ~collections.abc.Sequence[tuple[float | int | ~numbers.Real, float | int | ~numbers.Real]] = (), branch_gdf: ~geopandas.geodataframe.GeoDataFrame = <factory>, node_gdf: ~geopandas.geodataframe.GeoDataFrame = <factory>, censoring_area: ~geopandas.geodataframe.GeoDataFrame = <factory>, cache_results: bool = True, remove_z_coordinates_from_inputs: bool = True, _anisotropy: ~typing.Tuple[~numpy.ndarray, ~numpy.ndarray] | None = None, _parameters: ~typing.Dict[str, float] | None = None, _azimuth_set_relationships: ~pandas.core.frame.DataFrame | None = None, _trace_length_set_relationships: ~pandas.core.frame.DataFrame | None = None, _trace_intersects_target_area_boundary: ~numpy.ndarray | None = None, _branch_intersects_target_area_boundary: ~numpy.ndarray | None = 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 containing trace data i.e. shapely.geometry.LineString geometries.

• area_gdf – GeoDataFrame containing target area data i.e. (Multi)Polygon's.

• name – Name the Network.

• determine_branches_nodes – Whether to determine branches and nodes.

• snap_threshold – The snapping distance threshold to identify snapped traces.

• truncate_traces – Whether to crop the traces at the target area boundary.

• circular_target_area – Is the target are a circle.

• azimuth_set_names – Names of each azimuth set.

• azimuth_set_ranges – Ranges of each azimuth set.

• trace_length_set_names – Names of each trace length set.

• trace_length_set_ranges – Ranges of each trace length set.

• branch_length_set_names – Names of each branch length set.

• branch_length_set_ranges – Ranges of each branch length set.

• branch_gdf – GeoDataFrame containing branch data. It is recommended to let fractopo.Network determine both branches and nodes instead of passing them here.

• node_gdf – GeoDataFrame containing node data. It is recommended to let fractopo.Network determine both branches and nodes instead of passing them here.

• censoring_area – 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 – 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: GeoDataFrame | None = None, nodes: GeoDataFrame | None = None)

Determine and assign branches and nodes as attributes.

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

azimuth_set_ranges: Sequence[tuple[float | int | Real, 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: str | None) → LengthDistribution

Create structured LengthDistribution instance of branch length data.

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[float | int | Real, float | int | Real]] = ()

branch_lengths_powerlaw_fit(cut_off: float | None = None) → Fit | None

Determine powerlaw fit for branch lengths.

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: float | None = None, bounds_divider: float = 20.0, precursor_grid: GeoDataFrame | None = None, resolve_branches_nodes: bool = 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() → float

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.

export_network_analysis(output_path: Path, include_contour_grid: bool = True, contour_grid_cell_size: float | None = None, fits_to_plot: Tuple[Dist, ...] = (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: Callable, write_geodataframe_to_export_path: Callable, include_contour_grid: bool, contour_grid_cell_size: float | None, fits_to_plot: Tuple[Dist, ...])

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: float | None = None, branch_lengths_cut_off: float | None = None) → Dict[str, float | int | Real | str]

Collect numerical network attributes and return them as a dictionary.

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: str | None = None, color: str | None = None) → Tuple[Figure, Axes] | None

Plot anisotropy of connectivity plot.

plot_azimuth_crosscut_abutting_relationships() → Tuple[List[Figure], List[ndarray]]

Plot azimuth set crosscutting and abutting relationships.

plot_branch(label: str | None = None) → Tuple[Figure, Axes, TernaryAxesSubplot]

Plot ternary plot of branch types.

plot_branch_azimuth(label: str | None = None, append_azimuth_set_text: bool = False, add_abundance_order: bool = False, visualize_sets: bool = False, bar_color: str = 'darkgrey', plain: bool = False) → Tuple[AzimuthBins, Figure, PolarAxes]

Plot branch azimuth rose plot.

plot_branch_azimuth_set_count(label: str | None = None) → Tuple[Figure, Axes]

Plot branch azimuth set counts.

plot_branch_azimuth_set_lengths() → Tuple[List[Fit | None], List[Figure], List[Axes]]

Plot branch azimuth set lengths with fits.

plot_branch_length_set_count(label: str | None = None) → Tuple[Figure, Axes]

Plot branch length set counts.

plot_branch_lengths(label: str | None = None, fit: Fit | None = None, use_probability_density_function: bool = False, plain: bool = False, fits_to_plot: Tuple[Dist, ...] = (Dist.POWERLAW, Dist.LOGNORMAL, Dist.EXPONENTIAL)) → Tuple[Fit | None, Figure, Axes]

Plot branch length distribution with powerlaw fits.

plot_contour(parameter: str, sampled_grid: GeoDataFrame) → Tuple[Figure, Axes]

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.

plot_parameters(label: str | None = None, color: str | None = None) → Tuple[Figure, Axes] | None

Plot geometric and topological parameters.

plot_trace_azimuth(label: str | None = None, append_azimuth_set_text: bool = False, add_abundance_order: bool = False, visualize_sets: bool = False, bar_color: str = 'darkgrey', plain: bool = False) → Tuple[AzimuthBins, Figure, PolarAxes]

Plot trace azimuth rose plot.

plot_trace_azimuth_set_count(label: str | None = None) → Tuple[Figure, Axes]

Plot trace azimuth set counts.

plot_trace_azimuth_set_lengths() → Tuple[List[Fit | None], List[Figure], List[Axes]]

Plot trace azimuth set lengths with fits.

plot_trace_length_crosscut_abutting_relationships() → Tuple[List[Figure], List[ndarray]]

Plot length set crosscutting and abutting relationships.

plot_trace_length_set_count(label: str | None = None) → Tuple[Figure, Axes]

Plot trace length set counts.

plot_trace_lengths(label: str | None = None, fit: Fit | None = None, use_probability_density_function: bool = False, plain: bool = False, fits_to_plot: Tuple[Dist, ...] = (Dist.POWERLAW, Dist.LOGNORMAL, Dist.EXPONENTIAL)) → Tuple[Fit | None, Figure, Axes]

Plot trace length distribution with powerlaw fits.

plot_xyi(label: str | None = None) → Tuple[Figure, Axes, TernaryAxesSubplot]

Plot ternary plot of node types.

remove_z_coordinates_from_inputs: bool = True

representative_points() → List[Point]

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

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: str | None) → LengthDistribution

Create structured LengthDistribution instance of trace length data.

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[float | int | Real, float | int | Real]] = ()

trace_lengths_powerlaw_fit(cut_off: float | None = None) → Fit | None

Determine powerlaw fit for trace lengths.

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: Path, branches_name: str | None = None, nodes_name: str | None = 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: Callable) → Callable

Wrap methods that require determined topology.

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