These files were written by: G. V. DiRenzo If you have any questions, please email: gdirenzo@umass.edu USGS Disclaimer Unless otherwise stated, all data, metadata, and related materials are considered to satisfy the quality standards relative to the purpose for which the data were collected. Although these data and associated metadata have been reviewed for accuracy and completeness and approved for release by the U.S. Geological Survey (USGS), no warranty expressed or implied is made regarding the display or utility of the data for other purposes, nor on all computer systems, nor shall the act of distribution constitute any such warranty. README objective This file is intended to help navigate through the Data, Software, and Supplemental files associated with the manuscript: DiRenzo, G. V., D. A. W. Miller, E. H. C. Grant. Ignoring species availability biases occupancy estimates in single-scale occupancy models. All data in this repository was simulated. We navigate the user to the files where they can simulate the data, analyze the data, process the data, and create the manuscript figures and tables. With the code listed below, any user should be able to reproduce all of the tables and figures in the manuscript. In addition, the user should also be able to reproduce the RShiny app: https://gdirenzo.shinyapps.io/multi-scale-occ/ Table of Contents 1. Navigate to files that generate a spreadsheet with different parameter values and survey designs that were used to simulate datasets 2. Navigate to files that simulate & analyze data on the cluster when availability is constant across sites (Scenario 1) 3. Navigate to files that perform the post-processing for Section II. Q1 in the main text of the manuscript 4. Navigate to files that perform the post-processing for Section II. Q2 in the main text of the manuscript 5. Navigate to files that simulate & analyze data on the cluster when availability is heterogenous across sites (Scenario 2) 6. Navigate to files that simulate & analyze data on the cluster when availability is heterogenous across years (Scenario 3) 7. Navigate to files that simulate & analyze data on the cluster when availability is correlated to detection probability (Scenario 4) 8. Navigate to files that perform the post-processing for Section II. Q3 in the main text of the manuscript 9. List of other files/folders in the repo that are not listed here 10. RShiny app files ----------------------------------------------- 1. Navigate to files that generate a spreadsheet with different parameter values and survey designs that were used to simulate datasets across Scenarios 1 - 4 ----------------------------------------------- For code that generated the parameter values & sampling designs for Scenarios 1 & 2: Software/ParameterCombinations/LHS_parameter_combos.R This script generates 1 csv file: parameter_combos_TwoLevelAvail4.csv This file can be located in: Data/ParameterCombinations/parameter_combos_TwoLevelAvail4.csv Information related to fields are located in: Data/Metadata/TwoLevel-Metadata 2021 01 24.xml Once the file is open (in MetaData Wizard), navigate to "Entity and Attributes" along the top Then, along the left, there are several "Detailed" tabs - click through them and locate the one with the "Dataset Label" = parameter_combos_TwoLevelAvail4.cs Briefly, here is a description of each field in the file: parameter_combos_TwoLevelAvail4.csv n.site = Number of sites n.sec.surveys = Number of secondary surveys n.tier.surveys = Number of tertiary surveys psi = True Occupancy probability - on the logit scale availability = True Availability - on the logit scale detection = True Detection probability - on the logit scale For code that generated the parameter values & sampling designs for Scenarios 3 & 4: Software/ParameterCombinations/LHS_parameter_combos_years.R This script generates 1 csv file: parameter_combos_TwoLevelAvail_years.csv That file is located: Data/ParameterCombinations/parameter_combos_TwoLevelAvail_years.csv Information related to fields are located in: Data/Metadata/TwoLevel-Metadata 2021 01 24.xml Once the file is open (in MetaData Wizard), navigate to "Entity and Attributes" along the top Then, along the left, there are several "Detailed" tabs - click through them and locate the one with the "Dataset Label" = parameter_combos_TwoLevelAvail_years.csv Briefly, here is a description of each field in the file: parameter_combos_TwoLevelAvail_years.csv n.site = Number of sites n.sec.surveys = Number of secondary surveys n.tier.surveys = Number of tertiary surveys n.season = Number of years psi = True Occupancy probability - on the logit scale availability = True Availability - on the logit scale detection = True Detection probability - on the logit scale sd = Not used To find a detailed description of the fields in the file parameter_combos_TwoLevelAvail_years.csv, please navigate to: Data/Metadata/TwoLevel-Metadata 2021 01 24.xml This file can either be opened in a text editor or using the USGS software "Metadata wizard" (https://usgs.github.io/fort-pymdwizard/) ----------------------------------------------- 2. Navigate to files that simulate & analyze data on the cluster when availability is constant across sites (Scenario 1) ----------------------------------------------- Data simulated: Availability is constant across sites (but less than 1) Models used to analyze the data: (i) Constant multi-scale occupancy model and (iii) Constant single-scale occupancy model To simulate & analyze the datasets on the cluster: Software/SimulationCode/Scen1_Constant.sh The corresponding R file for the cluster script is: Software/SimulationCode/Scen1_Constant.R ----------------------------------------------- 3. Navigate to files that perform the post-processing for Section II. Q1 in the main text of the manuscript ----------------------------------------------- For code that does the post-processing for Section II. Q1.: Software/PostProcessing/II. Q1. TwoLevelAvail_SampDesign_ParamEstimate.R This file generates: Table S2; Figures S1, S2, S3, and S4 These files can be located in: Supplemental-Information/Tables/TableS2_ParamCombos.csv Supplemental-Information/Figures/ParameterEstimates/FigS1_ERROR_SampDesign_2v4tertsurvs.pdf Supplemental-Information/Figures/ParameterEstimates/FigS2_WIDTH_SampDesign_2v4tertsurvs.pdf Supplemental-Information/Figures/ParameterEstimates/FigS3_BIAS_SampDesign_2v4tertsurvs.pdf Supplemental-Information/Figures/ParameterEstimates/FigS4_COV_SampDesign_2v4tertsurvs.pdf ----------------------------------------------- 4. Navigate to files that perform the post-processing for Section II. Q2. ----------------------------------------------- For code that does the post-processing for Section II. Q2.: Software/SamplingDesign/PostProcessing/II. Q2. TwoLevelAvail_GenRec.R This file generates: Table 1 This file can be found in: Supplemental-Information/Tables/Table1_GenSampRec.csv ----------------------------------------------- 5. Navigate to files that simulate & analyze data on the cluster when availability is heterogenous across sites (Scenario 2) ----------------------------------------------- Scenario 2 Data simulated: Availability is heterogenous across sites Models used: (i) the multi-scale occupancy model with constant availability across sites, (ii) the multi-scale occupancy model with a random site-effects term for availability, (iii) the single-scale occupancy model with constant detection across sites, and (iv) the single-scale occupancy model with a random site-effects term for detection To simulate & analyze the datasets on the cluster: Software/SimulationCode/Scen2_HeteroSite.sh The corresponding R file for the cluster script is: Software/SimulationCode/Scen2_HeteroSite.R ----------------------------------------------- 6. Navigate to files that simulate & analyze data on the cluster when availability is heterogenous across years (Scenario 3) ----------------------------------------------- Scenario 3 Data simulated: Availability is heterogenous across years Models used: (i) the multi-scale occupancy model with constant availability across years, (ii) the multi-scale occupancy model with a random year-effects term for availability, (iii) the single-scale occupancy model with constant detection across years, and (iv) the single-scale occupancy model with a random year-effects term for detection To simulate & analyze the datasets on the cluster: Software/SimulationCode/Scen3_HeteroYear.sh The corresponding R file for the cluster script is: Software/SimulationCode/Scen3_HeteroYear.R ----------------------------------------------- 7. Navigate to files that simulate & analyze data on the cluster when availability is correlated to detection probability (Scenario 4) ----------------------------------------------- Scenario 4 Data simulated: Availability correlated to detection probability Models used: (i) the multi-scale occupancy model with constant availability across years, (ii) the multi-scale occupancy model with a random year-effects term for availability, (iii) the single-scale occupancy model with constant detection across years, and (iv) the single-scale occupancy model with a random year-effects term for detection To simulate & analyze the datasets on the cluster: Software/SimulationCode/Scen4_Corr.sh The corresponding R file for the cluster script is: Software/SimulationCode/Scen4_Corr.R ----------------------------------------------- 8. Navigate to files that perform the post-processing for Section II. Q3 in the main text of the manuscript ----------------------------------------------- For code that does the post-processing for Section II. Q3.: Software/PostProcessing/II. Q3. Scenario 1-4- Model performance.R This file generates: Figure 2, 3, 4, & 5 These files can be located in: Supplemental-Information/Figures/ModComp/Fig2 - Accuracy.pdf Supplemental-Information/Figures/ModComp/Fig3 - Precision.pdf Supplemental-Information/Figures/ModComp/Fig4 - Bias.pdf Supplemental-Information/Figures/ModComp/Fig5 - Coverage.pdf ----------------------------------------------- 9. List of other files/folders in the repo that are not listed here ----------------------------------------------- Folder that holds all of the manuscript figures Supplemental-Information/Figures/ Main text figures: Supplemental-Information/Figures/ModComp/ Appendix figures: Supplemental-Information/Figures/ParameterEstimates Folder that holds all of the manuscript tables Supplemental-Information/Tables Folder that holds all of the model output generated by Scenario 1 Data/ModelOutput_Scen1_TwolevelSim Information related to fields are located in: Data/Metadata/TwoLevel-Metadata 2021 01 24.xml Once the file is open (in MetaData Wizard), navigage to "Entity and Attributes" along the top Then, along the left, there are several "Detailed" tabs - click through them and locate the one with the "Dataset Label" = Results_TwoLevelAvail_2lev_x.csv Briefly, here is a description of each field in the file: Results_TwoLevelAvail_2lev_x.csv n.site = Number of sites n.sec.surveys = Number of secondary surveys n.tier.surveys = Number of tertiary surveys psi = True occupancy probability- logit scale availability = True availability- logit scale detection< = True detection probability- logit scale Prop_avail = NA- not used Prop_detect = NA- not used Prop_overall = NA- not used Prop_site = NA- not used TwoLev_alpha.psi_Mean = Multi-scale occupancy model mean estimate of occupancy probability on the logit scale TwoLev_alpha.psi_ylo = Multi-scale occupancy model lower 95% CI estimate of occupancy probability on the logit scale TwoLev_alpha.psi_yhi = Multi-scale occupancy model upper 95% CI estimate of occupancy probability on the logit scale TwoLev_alpha.availability_Mean = Multi-scale occupancy model mean estimate of availability probability on the logit scale TwoLev_alpha.availability_ylo = Multi-scale occupancy model lower 95% CI estimate of availability probability on the logit scale TwoLev_alpha.availability_yhi = Multi-scale occupancy model upper 95% CI estimate of availability probability on the logit scale TwoLev_alpha.p_Mean = Multi-scale occupancy model mean estimate of detection probability on the logit scale TwoLev_alpha.p_ylo = Multi-scale occupancy model lower 95% CI estimate of detection probability on the logit scale TwoLev_alpha.p_yhi = Multi-scale occupancy model upper 95% CI estimate of detection probability on the logit scale OneLev_alpha.psi_Mean = Single-scale occupancy model mean estimate of occupancy probability on the logit scale OneLev_alpha.psi_ylo = Single-scale occupancy model lower 95% CI estimate of occupancy probability on the logit scale OneLev_alpha.psi_yhi = Single-scale occupancy model upper 95% CI estimate of occupancy probability on the logit scale OneLev_alpha.p_Mean = Single-scale occupancy model mean estimate of detection probability on the logit scale OneLev_alpha.p_ylo = Single-scale occupancy model lower 95% CI estimate of detection probability on the logit scale OneLev_alpha.p_yhi = Single-scale occupancy model upper 95% CI estimate of detection probability on the logit scale Rhat_check.2lev = Rhat check for convergence of the Multi-scale occupancy model. Value = 1 means yes the model converged. Value = 0 or NA means no the model did not converge Rhat_check.1lev = Rhat check for convergence of the Single-scale occupancy model. Value = 1 means yes the model converged.Value = 0 or NA means no the model did not converge Folder that holds all of the model output generated by Scenario 2 Data/ModelOutput_Scen2_HeteroSite Information related to fields are located in: Data/Metadata/TwoLevel-Metadata 2021 01 24.xml Once the file is open (in MetaData Wizard), navigate to "Entity and Attributes" along the top Then, along the left, there are several "Detailed" tabs - click through them and locate the one with the "Dataset Label" = Results_TwoLevelAvail_Hetero_x.csv Briefly, here is a description of each field in the file: Results_TwoLevelAvail_Hetero_x.csv n.site = Number of sites n.sec.surveys = Number of secondary surveys n.tier.surveys = Number of tertiary surveys psi = True occupancy probability- logit scale availability = True availability- logit scale detection = True detection probability- logit scale stdev = NA- not used Prop_avail = NA- not used Prop_detect = NA- not used Prop_overall = NA- not used Prop_site = NA- not used TwoLev_Con_alpha.psi_Mean = Multi-scale occupancy model with fixed parameters mean estimate of occupancy probability on the logit scale TwoLev_Con_alpha.psi_ylo = Multi-scale occupancy model with fixed parameters lower 95% CI estimate of occupancy probability on the logit scale TwoLev_Con_alpha.psi_yhi = Multi-scale occupancy model with fixed parameters upper 95% CI estimate of occupancy probability on the logit scale TwoLev_Con_alpha.availability_Mean = Multi-scale occupancy model with fixed parameters mean estimate of availability probability on the logit scale TwoLev_Con_alpha.availability_ylo = Multi-scale occupancy model with fixed parameters lower 95% CI estimate of availability probability on the logit scale TwoLev_Con_alpha.availability_yhi = Multi-scale occupancy model with fixed parameters upper 95% CI estimate of availability probability on the logit scale TwoLev_Con_alpha.p_Mean = Multi-scale occupancy model with fixed parameters mean estimate of detection probability on the logit scale TwoLev_Con_alpha.p_ylo = Multi-scale occupancy model with fixed parameters lower 95% CI estimate of detection probability on the logit scale TwoLev_Con_alpha.p_yhi< = Multi-scale occupancy model with fixed parameters upper 95% CI estimate of detection probability on the logit scale TwoLev_Hetero_alpha.psi_Mean = Multi-scale occupancy model with random-effects parameters mean estimate of occupancy probability on the logit scale TwoLev_Hetero_alpha.psi_ylo = Multi-scale occupancy model with random-effects parameters lower 95% CI estimate of occupancy probability on the logit scale TwoLev_Hetero_alpha.psi_yhi = Multi-scale occupancy model with random-effects parameters upper 95% CI estimate of occupancy probability on the logit scale TwoLev_Hetero_alpha.availability_Mean = Multi-scale occupancy model with random-effects parameters mean estimate of availability probability on the logit scale TwoLev_Hetero_alpha.availability_ylo = Multi-scale occupancy model with random-effects parameters lower 95% CI estimate of availability probability on the logit scale TwoLev_Hetero_alpha.availability_yhi = Multi-scale occupancy model with random-effects parameters upper 95% CI estimate of availability probability on the logit scale TwoLev_Hetero_alpha.p_Mean< = Multi-scale occupancy model with random-effects parameters mean estimate of detection probability on the logit scale TwoLev_Hetero_alpha.p_ylo = Multi-scale occupancy

1. Most applications of single-scale occupancy models do not differentiate between availability and detectability, even though species availability is rarely equal to one. Species availability can be estimated using multi-scale occupancy models, and the availability process includes elements of species movement, behavior, and phenology. However, for the practical application of multi-scale occupancy models, it can be unclear what a robust sampling design looks like and what the statistical properties of the multi-scale and single-scale occupancy models are when availability is less than one. 2. Using simulations, we explore the following common questions asked by ecologists during the design phase of a field study: (Q1) what is a robust sampling design for the multi-scale occupancy model when there are a priori expectations of parameter estimates?, (Q2) what is a robust sampling design when we have no expectations of parameter estimates?, and (Q3) can a single-scale occupancy model with a random effects term adequately absorb the extra heterogeneity produced when availability is less than one and provide reliable estimates of occupancy probability?. 3. Our results show that there is a tradeoff between the number of sites and surveys needed to achieve a specified level of acceptable error for occupancy estimates using the multi-scale occupancy model. We also document that when species availability is low (< 0.40 on the probability scale), then single-scale occupancy models underestimate occupancy by as much as 0.40 on the probability scale, produce overly precise estimates, and provide poor parameter coverage. This pattern was observed when a random effects term was and was not included in the single-scale occupancy model, suggesting that adding a random-effects term does not adequately absorb the extra heterogeneity produced by the availability process. In contrast, when species availability was high (> 0.60), single-scale occupancy models performed similarly to the multi-scale occupancy model. 4. As a companion, we provide an RShiny app that allows users to further explore our results and sampling designs across a number of different scenarios https://gdirenzo.shinyapps.io/multi-scale-occ/. Our results suggest that unaccounted for availability can lead to underestimating species distributions when using single-scale occupancy models, which can have large implications on ecological inference and predictions for practitioners, such as those working at the front lines of invasion ecology, disease emergence, and species conservation.