| Title: | Create Networks of Dendrochronological Series using Pairwise Similarity |
|---|---|
| Description: | Creating dendrochronological networks based on the similarity between tree-ring series or chronologies. The package includes various functions to compare tree-ring curves building upon the 'dplR' package. The networks can be used to visualise and understand the relations between tree-ring curves. These networks are also very useful to estimate the provenance of wood as described in Visser (2021) <DOI:10.5334/jcaa.79> or wood-use within a structure/context/site as described in Visser and Vorst (2022) <DOI:10.1163/27723194-bja10014>. |
| Authors: | Ronald Visser [aut, cre]  ,
Angelino Salentino [ctb] ,
Andy Bunn [ctb] ,
Kaija Gahm [rev] (Kaija Gahm reviewed the package for rOpenSci, see
https://github.com/ropensci/software-review/issues/627#issuecomment-1993235710),
Zachary Gajewski [rev] (Zachary Gajewski reviewed the package for
rOpenSci, see
https://github.com/ropensci/software-review/issues/627#issuecomment-2037644081) |
| Maintainer: | Ronald Visser <[email protected]> |
| License: | GPL (>= 3) |
| Version: | 0.5.4 |
| Built: | 2024-08-29 22:56:15 UTC |
| Source: | https://github.com/ropensci/dendroNetwork |
Function to determine communities in a network using clique percolation method (Palla et al., 2005). Communities are created based on cliques. Cliques are subsets of a network that can be considered complete (sub)networks. The size of the cliques to be used to community detection is part of the input of the function.
clique_community_names(g, k = 3)clique_community_names(g, k = 3)
g |
network object (igraph) |
k |
clique size to be used. The default is set to smallest possible size (3) |
a dataframe with node names and community name. The community is named as CPM_Kk_number_of_community with k replaced by the value of k.
Angelo Salatino
Ronald Visser
Palla, G., Derényi, I., Farkas, I., & Vicsek, T. (2005). Uncovering the overlapping community structure of complex networks in nature and society. Nature, 435(7043), 814-818.
Code adapted from source: https://github.com/angelosalatino/CliquePercolationMethod-R/blob/master/clique.community.R
hol_sim <- sim_table(hol_rom) g_hol <- dendro_network(hol_sim) clique_community_names(g_hol, k = 3)hol_sim <- sim_table(hol_rom) g_hol <- dendro_network(hol_sim) clique_community_names(g_hol, k = 3)
Function to determine communities in a network using clique percolation method (Palla et al., 2005). Communities are created based on cliques. Cliques are subsets of a network that can be considered complete (sub)networks. The size of the cliques to be used to community detection is part of the input of the function. This function uses parallelisation and should be used for larger networks.
clique_community_names_par(g, k = 3, n_core = 4)clique_community_names_par(g, k = 3, n_core = 4)
g |
network object (igraph) |
k |
clique size to be used, default set to smallest possible size (3) |
n_core |
number of cores to be used for parrallisation, defaults to 4 |
a dataframe with node names and community name. The community is named as CPM_Kk_number_of_community with k replaced by the value of k.
Angelo Salatino
Ronald Visser
Palla, G., Derényi, I., Farkas, I., & Vicsek, T. (2005). Uncovering the overlapping community structure of complex networks in nature and society. Nature, 435(7043), 814-818.
Code adapted from source: https://github.com/angelosalatino/CliquePercolationMethod-R/blob/master/clique.community.opt.par.R
## Not run: hol_sim <- sim_table(hol_rom) g_hol <- dendro_network(hol_sim, r_threshold = 0.4, sgc_threshold = 0.4) clique_community_names_par(g_hol, k = 3, n_core = 2) ## End(Not run)## Not run: hol_sim <- sim_table(hol_rom) g_hol <- dendro_network(hol_sim, r_threshold = 0.4, sgc_threshold = 0.4) clique_community_names_par(g_hol, k = 3, n_core = 2) ## End(Not run)
Function that creates a Pearson correlation matrix of two rwl objects compared. If the same rwl-object is passed to the function, the correlation between all series is calculated. In addition, the number of overlapping tree-rings is part of the output. The results can be used to calculate the Students' t value
cor_mat_overlap(x, y, minoverlap)cor_mat_overlap(x, y, minoverlap)
x |
rwl object of tree-ring series |
y |
rwl object of tree-ring series |
minoverlap |
the correlation will only be calculated if the number of overlapping tree-rings is equal or larger than this value |
The function is an adaptation of the function cor.with.limit.R() from https://github.com/AndyBunn/dplR/blob/master/R/rwi.stats.running.R. The new function is optimized and also outputs the number of overlapping rings.
a list with two matrices: one with the correlation values and one with the number of overlapping tree rings for each correlation value. The matrices have row names and column names of the compared tree-ring curves
Andy Bunn
Ronald Visser
rwl_object1 <- hol_rom rwl_object2 <- hol_rom cor_mat_overlap(rwl_object1, rwl_object2, 50) cor_mat_overlap(rwl_object1, rwl_object1, 50)rwl_object1 <- hol_rom rwl_object2 <- hol_rom cor_mat_overlap(rwl_object1, rwl_object2, 50) cor_mat_overlap(rwl_object1, rwl_object1, 50)
Cleaning nearly all styles in cytoscape session and import simple styles
cyto_clean_styles()cyto_clean_styles()
Cytoscape cleaned of styles and only styles with white and grey nodes.
## Not run: cyto_clean_styles() ## End(Not run)## Not run: cyto_clean_styles() ## End(Not run)
Function to create a style in Cytoscape to visualise the communities in a network using clique percolation method (CPM: Palla et al., 2005). See also: find_all_cpm_com() Each node is filled with the colour of the community. If a node is part of several communities a pie chart is used to show the various community colours. The function uses a graph as input and the number of cliques (default = 3). The style can be specified or automatically named based on the name of the network an the number of cliques. Before starting this function, Cytoscape must be up and running!
cyto_create_cpm_style(graph_input, k = 3, com_k = NULL, style_name = "auto")cyto_create_cpm_style(graph_input, k = 3, com_k = NULL, style_name = "auto")
graph_input |
the graph with the CPM communities |
k |
clique size for the visualisation. This should be an integer with the value 3 or higher |
com_k |
data_frame with the communities for the specific clique size (two columns: node and com_name). This is the result of clique_community_names_par() or clique_community_names() |
style_name |
name of the output style in Cytoscape. If set to "auto", the style is derived from the name of the network and value for k |
The style applied in Cytoscape, no objects in R as return.
## Not run: data(hol_rom) sim_table_hol <- sim_table(hol_rom) g_hol <- dendro_network(sim_table_hol) hol_com_cpm_k3 <- clique_community_names(g_hol, k = 3) cyto_create_graph(g_hol) cyto_create_cpm_style(g_hol, k = 3, com_k = hol_com_cpm_k3) ## End(Not run)## Not run: data(hol_rom) sim_table_hol <- sim_table(hol_rom) g_hol <- dendro_network(sim_table_hol) hol_com_cpm_k3 <- clique_community_names(g_hol, k = 3) cyto_create_graph(g_hol) cyto_create_cpm_style(g_hol, k = 3, com_k = hol_com_cpm_k3) ## End(Not run)
Function to create a style in Cytoscape to visualise the communities in a network using the Girvan-Newman method for community detection. Each node is filled with a separate colour for each community. Before starting this function, Cytoscape must be up and running!
cyto_create_gn_style(graph_input, gn_coms = NULL, style_name = "auto")cyto_create_gn_style(graph_input, gn_coms = NULL, style_name = "auto")
graph_input |
the graph with the CPM communities |
gn_coms |
GN communities in graph_input. This is the result of gn_names(). If this is not given this will be calculated in the function |
style_name |
name of the output style in Cytoscape. If set to "auto", the style is derived from the name of the network and value for k |
The style applied in Cytoscape, no objects in R as return.
## Not run: data(hol_rom) sim_table_hol <- sim_table(hol_rom) g_hol <- dendro_network(sim_table_hol) g_hol_gn <- gn_names(g_hol) cyto_create_graph(g_hol) cyto_create_gn_style(g_hol, gn_coms = g_hol_gn) ## End(Not run)## Not run: data(hol_rom) sim_table_hol <- sim_table(hol_rom) g_hol <- dendro_network(sim_table_hol) g_hol_gn <- gn_names(g_hol) cyto_create_graph(g_hol) cyto_create_gn_style(g_hol, gn_coms = g_hol_gn) ## End(Not run)
Function to create a network in cytoscape (https://cytoscape.org/) Cytoscape must be running before executing this function
cyto_create_graph( graph_input, network_name = substitute(graph_input), collection_name = "default", style_name = "default", CPM_table = NULL, GN_table = NULL )cyto_create_graph( graph_input, network_name = substitute(graph_input), collection_name = "default", style_name = "default", CPM_table = NULL, GN_table = NULL )
graph_input |
igraph network used to create network in Cytoscape |
network_name |
name of the network in Cytoscape, defaults to the name of variable that is the network in R |
collection_name |
name of the collection in Cytoscape (default = default) |
style_name |
name of the style in Cytoscape (default = default) |
CPM_table |
table with the name of the nodes in the first column and the CPM-communities in other columns. This is the result of find_all_cpm_com() |
GN_table |
two column table with the name of the nodes in the first column and the Girvan-Newman-communities in other columns |
a graph in Cytoscape
## Not run: data(hol_rom) sim_table_hol <- sim_table(hol_rom) g_hol <- dendro_network(sim_table_hol) hol_com_cpm_all <- find_all_cpm_com(g_hol) g_hol_gn <- gn_names(g_hol) cyto_create_graph(g_hol, CPM_table = hol_com_cpm_all, GN_table = g_hol_gn) ## End(Not run)## Not run: data(hol_rom) sim_table_hol <- sim_table(hol_rom) g_hol <- dendro_network(sim_table_hol) hol_com_cpm_all <- find_all_cpm_com(g_hol) g_hol_gn <- gn_names(g_hol) cyto_create_graph(g_hol, CPM_table = hol_com_cpm_all, GN_table = g_hol_gn) ## End(Not run)
Function to create dendrochronological networks based on the similarity. The input for this function is a similarity table created with the sim_table() function. The thresholds are set to the defaults (Visser 2021).
dendro_network( sim_table, r_threshold = 0.5, sgc_threshold = 0.7, p_threshold = 1e-04 )dendro_network( sim_table, r_threshold = 0.5, sgc_threshold = 0.7, p_threshold = 1e-04 )
sim_table |
a table of similarities created by the sim_table() function |
r_threshold |
all correlations equal or above this value are taken into account for the creation of edges. If you want all positive correlations included set this to 0. |
sgc_threshold |
all sgc-values equal or above this value are taken into account for the creation of edges. |
p_threshold |
all probabilities of exceedence equal or below this value are taken into account for the creation of edges. |
A simplified network of tree-ring material with the edges defined by the similarity.
Visser, RM. 2021a Dendrochronological Provenance Patterns. Network Analysis of Tree-Ring Material Reveals Spatial and Economic Relations of Roman Timber in the Continental North-Western Provinces. Journal of Computer Applications in Archaeology 4(1): 230–253. DOI: https://doi.org/10.5334/jcaa.79.
data(hol_rom) sim_table_hol <- sim_table(hol_rom) dendro_network(sim_table_hol) dendro_network(sim_table_hol, r_threshold = 0.4, sgc_threshold = 0.6)data(hol_rom) sim_table_hol <- sim_table(hol_rom) dendro_network(sim_table_hol) dendro_network(sim_table_hol, r_threshold = 0.4, sgc_threshold = 0.6)
Function to determine all CPM-communities in a network (or graph)
find_all_cpm_com(graph_input, n_core = 0)find_all_cpm_com(graph_input, n_core = 0)
graph_input |
the graph for find all CPM communities in |
n_core |
this defaults to 0, if a number larger than 1 is given the community detection is performed using parallel computing |
data frame with at least two columns. The first column are the node names and the further columns represent the CPM-communities, with 1 denoting the membership in a community.
data(hol_rom) sim_table_hol <- sim_table(hol_rom) g_hol <- dendro_network(sim_table_hol) hol_com_cpm_all <- find_all_cpm_com(g_hol)data(hol_rom) sim_table_hol <- sim_table(hol_rom) g_hol <- dendro_network(sim_table_hol) hol_com_cpm_all <- find_all_cpm_com(g_hol)
Function to determine the communities in a network using the Girvan-Newman algorithm. This function uses the cluster_edge_betweenness() function from the iGraph package, but creates a more user-friendly output that includes the names of the nodes.
gn_names(g)gn_names(g)
g |
input graph or network that is used for community detection |
References Girvan, M and Newman, MEJ. 2002 Community structure in social and biological networks. Proceedings of the National Academy of Sciences of the United States of America 99(12): 7821–7826. DOI: https://doi.org/10.1073/pnas.122653799. Newman, MEJ and Girvan, M. 2004 Finding and evaluating community structure in networks. Physical Review E 69(2): 026113. DOI: https://doi.org/10.1103/PhysRevE.69.026113.
the names of the nodes in the various communities
hol_sim <- sim_table(hol_rom) g_hol <- dendro_network(hol_sim) gn_names(g_hol)hol_sim <- sim_table(hol_rom) g_hol <- dendro_network(hol_sim) gn_names(g_hol)
Dendrochronological site chronologies published by Hollstein (1972, 1980). These 52 (pre) Roman site chronologies date between 502 BC and AD 550. This selection of (pre)Roman site-chronologies are also used by Visser (2021) and made available as Visser (2022).
data(hol_rom)data(hol_rom)
An object of class "rwl".
Hollstein, E. 1972 Dendrochronologische Datierung von Hölzern aus Wederath (Belginum). Trierer Zeitschrift 35: 123–125.
Hollstein, E. 1980. Mitteleuropäische Eichenchronologie. Trierer Dendrochronologische Forschungen zur Archäologie und Kunstgeschichte. Trierer Grabungen und Forschungen 11. Mainz am Rhein: Verlag Philipp von Zabern.
Visser, RM. 2021 Dendrochronological Provenance Patterns. Network Analysis of Tree-Ring Material Reveals Spatial and Economic Relations of Roman Timber in the Continental North-Western Provinces. Journal of Computer Applications in Archaeology 4(1): 230–253. DOI: https://doi.org/10.5334/jcaa.79.
Visser, RM. 2022 Dendrochronological Provenance Patterns. Code and Data of Network Analysis of Tree-Ring Material. DOI: https://doi.org/10.5281/zenodo.7157744.
data(hol_rom) sim_table(hol_rom, last_digit_radius = TRUE)data(hol_rom) sim_table(hol_rom, last_digit_radius = TRUE)
Dendrochronological site chronologies published by Visser (2021, 2022). These (pre) Roman site chronologies date between 520 BC and AD 663 and are based on the material of RING (full references to the source data can be found in the supplementary data of Visser 2021) The series are named based on their location, species and type of standardisation For example: ABC_Q1M or ABC_Q1C consist of the same material from the site ABC (Abcoude), species Q(uercus), chronology 1 and standardisation C(ofecha) and M(eans). See Visser(2021) for more explanation.
data(RING_Visser_2021)data(RING_Visser_2021)
An object of class "rwl".
Visser, RM. 2021 Dendrochronological Provenance Patterns. Network Analysis of Tree-Ring Material Reveals Spatial and Economic Relations of Roman Timber in the Continental North-Western Provinces. Journal of Computer Applications in Archaeology 4(1): 230–253. DOI: https://doi.org/10.5334/jcaa.79.
Visser, RM. 2022 Dendrochronological Provenance Patterns. Code and Data of Network Analysis of Tree-Ring Material. DOI: https://doi.org/10.5281/zenodo.7157744.
data(RING_Visser_2021) sim_table(RING_Visser_2021, last_digit_radius = TRUE)data(RING_Visser_2021) sim_table(RING_Visser_2021, last_digit_radius = TRUE)
Function to calculate various similarity measures for the creation of dendrochronological networks as described by Visser (2021a). The function results in a list of all similarities of all comparisons between the tree-ring series in trs1 (or between trs1 and trs2). The resulting list includes the overlap, correlation (both with and without Hollstein-transformation), the t-value based on these correlations, Synchronous Growth Changes (SGC), Semi Synchronous Growth Changes (SSGC), and the related probability of exceedence (p).The last three (SGC, SSGC and p) are explained in Visser (2021b).
sim_table(trs1, trs2=NULL, min_overlap=50, last_digit_radius=FALSE)sim_table(trs1, trs2=NULL, min_overlap=50, last_digit_radius=FALSE)
trs1 |
Rwl object with first tree-ring series to be compared with trs2. A rwl object is a data.frame with series or tree-ring widths as columns and years as rows. This object is created or read by using the dplR-package |
trs2 |
Optional second rwl object with second tree-ring series to be compared with trs1. Use this is you have two different datasets that you want to compare. Otherwise all series in trs1 are pair wise compared. |
min_overlap |
If the overlap of the compared series is longer or equal than this minimal value, the similarities will be calculated for the comparison |
last_digit_radius |
Set this to TRUE if the last digit of a series name is the radius of the tree-ring series |
The resulting list includes the names of the compared series, overlap, correlation (both with and without Hollstein-transformation), t-value based on these correlations, SGC, SSGC and the related probability of exceedence.
Visser, RM. 2021a Dendrochronological Provenance Patterns. Network Analysis of Tree-Ring Material Reveals Spatial and Economic Relations of Roman Timber in the Continental North-Western Provinces. Journal of Computer Applications in Archaeology 4(1): 230–253. DOI: https://doi.org/10.5334/jcaa.79.
Visser, RM. 2021b On the similarity of tree-ring patterns: Assessing the influence of semi-synchronous growth changes on the Gleichläufigkeitskoeffizient for big tree-ring data sets. Archaeometry 63(1): 204–215. DOI: https://doi.org/10.1111/arcm.12600.
data(hol_rom) sim_table(hol_rom) sim_table(hol_rom, last_digit_radius = TRUE) sim_table(hol_rom, min_overlap = 25) sim_table(hol_rom, min_overlap = 100, last_digit_radius = TRUE)data(hol_rom) sim_table(hol_rom) sim_table(hol_rom, last_digit_radius = TRUE) sim_table(hol_rom, min_overlap = 25) sim_table(hol_rom, min_overlap = 100, last_digit_radius = TRUE)
Function to determine the Students' t-value using the correlation and the number of compare values (tree-rings)
t_value(r, n)t_value(r, n)
r |
correlation value. |
n |
number of overlapping tree-rings/compared values. |
Students' t value as a numeric.
t_value(0.5, 100)t_value(0.5, 100)
Function to normalize tree-ring values according to Hollsteins transformation to Wuchswerte
wuchswerte(x)wuchswerte(x)
x |
tree-ring series |
Published on pages 14-15 in Hollstein, E. 1980. Mitteleuropäische Eichenchronologie. Trierer Dendrochronologische Forschungen zur Archäologie und Kunstgeschichte. Trierer Grabungen und Forschungen 11. Mainz am Rhein: Verlag Philipp von Zabern.
tree-ring series normalized according to Hollstein (1980, 14-15)
data(hol_rom) wuchswerte(hol_rom) # to convert a rwl object into wuchwerte use: dplR::as.rwl(apply(hol_rom, 2, wuchswerte))data(hol_rom) wuchswerte(hol_rom) # to convert a rwl object into wuchwerte use: dplR::as.rwl(apply(hol_rom, 2, wuchswerte))