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 (Tuple[str, ...]) – Names of each azimuth set.

• azimuth_set_ranges (Tuple[Tuple[float, float], ...]) – Ranges of each azimuth set.

• trace_length_set_names (Tuple[str, ...]) – Names of each trace length set.

• trace_length_set_ranges (Tuple[Tuple[float, float], ...]) – Ranges of each trace length set.

• branch_length_set_names (Tuple[str, ...]) – Names of each branch length set.

• branch_length_set_ranges (Tuple[Tuple[float, float], ...]) – 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: Tuple[str, ...] = ('1', '2', '3')

azimuth_set_ranges: Tuple[Tuple[float, float], ...] = ((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: Tuple[str, ...] = ()

branch_length_set_ranges: Tuple[Tuple[float, float], ...] = ()

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)

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.

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, 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)

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)

Plot trace length distribution with powerlaw fits.

Return type:

Tuple[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: Tuple[str, ...] = ()

trace_length_set_ranges: Tuple[Tuple[float, float], ...] = ()

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