####################################### # SecSel, a software tool for conservation prioritization # # 2020-12-10 ####################################### Name of software: SecSel Software access: http://www.nies.go.jp/biology/en/data/tool/secsel/index.html Developer: TAKENAKA, Akio Source language: Python 3.X Availability and cost: open source Released under the MIT license https://opensource.org/licenses/mit-license.php [About this document] This document provides an introduction to the Python package SecSel, which helps design protected areas for biodiversity conservation. This is a quick reference to understand basic concepts and manipulation to start simple analysis by SecSel. Please see "readme_more.txt" for more details [What is SecSel?] SecSel, a protected-area prioritization tool, has been developed to help design areas that efficiently protect various biodiversity features which distribute in scattering manner over wide region. SecSel can be applied to land-use design including not only biodiversity but also ecosystem functions and other purposes of land use. In the analysis by SecSel, a target region is split into small parts called "sites". A protected area is a set of sites. SecSel selects a protected area in a target region on the basis of values of biodiversity features in each site The evaluation metrics of the value should be quantitative but need not be ratio scale. The minimum requirement of the input data is that they are ordinal, and SecSel utilize semi-quantitative data. In SecSel, the conservation target is the number of local units with high values of each feature to be protected in the area. When the values of biodiversity features are roughly estimated, there are many ties between local units and the selection of sites will be more flexible. SecSel also considers the cost of including each site in the protected area, the compactness of the area, and conflicts among features, including conflicts between conservation and utilization of land or specific ecosystem functions. SecSel is a package coded in Python 3. It is executable in the execution environment for Python irrespective of operating system. To use SecSel, you first need to install the package and import secsel in your Python script. Thus, some knowledge of Python programing is required to use it. [Installation of SecSel] First, download secsel_X_X_X.zip from the website below (X_X_X represents the version of SecSel): http://www.nies.go.jp/biology/en/data/tool/secsel/index.html secsel_X_X_X.zip includes package of SecSel. The package secsel can be installed using pip, the package installer for Python. First, extract secsel_X_X_X.zip in an arbitrary working directory. Open a command prompt or terminal (how to open it depends on OS) in the working directory where you extracted the zip file, and execute the following command (including the last period, which represents the current working directory). pip install . if you see the following in the terminal, Successfully installed secsel-X.X.X The installation is successful. Then enter pip show secsel It will show the information of secsel package installed. *If you have an older version of pip, you'll get an instruction to version up it. It's easy to update following the instructions, but there is no problem to use SecSel if you leave it as it is. [Execution test] You will see SecSel works on your system in the following test. Extract the test_dataset.zip in the appropriate directory. The zip file is available in the same website as the secsel package. It includes some sample files useful to learn how to use SecSel. In your command prompt or terminal in the working directory with unzipped files, enter the following. python run_secsel_example.py parameters.txt Some rows of messages appear, and if you see ---completed--- in the last, you succeeded to execute SecSel. If you additionally enter python map_results.py foo-01_PA.txt Then, a map pops up, which show the sites selected as a protected area by SecSel. The cursor returns to the command prompt when you close the pop-up window. Note that the script map_results.py requires the Python package matplotlib, a visualization library. Detailed settings for site selection are given in a parameter file. Explanations about the parameter file, outputs, and visualization of the results of site selection are in the later part of this document. [Terms used in SecSel] The followings are the main terms used in SecSel. - feature (target of conservation or use) A feature is a biodiversity item, land use type, or ecosystem function at any level. Biodiversity features include taxonomic classification of at any level, including the type of vegetations, habitat, types and ecosystems. Land use types and ecosystem functions include functions at any level, including agricultural and silvicultural land use. Any land use not related to ecosystems, such as urban areas and power plants, may also be included in the analysis. - site A site is a spatial unit for conservation and land-use planning. SecSel selects a set of sites as a protected area. - local unit A local unit is a fragment of any feature within a site. For example, a population of a species within a site. - value Value of each local unit to conserve or to use. Examples are size classes of a population or animals or plants in a site (large, medium, small), and rough amount of ecosystem services. For the analysis by SecSel, the value of each local unit is quantified on an ordinal, interval or ratio scale. Each local unit is assigned to an arbitrary rank level for the analysis by SecSel. Local units with relatively high conservation/use values should be highly ranked to conserve/use features. The number of ranks is arbitrary and can differ among features. On the one hand, the higher the resolution, the more precise the selection of the highest priority local units will be obtained. On the other hand, low resolution enables more flexible selection of local units. Flexibility makes it possible to select a compact set of sites to achieve targets for multiple features. - top-N included If top N local units of a feature that have high ranks are included in a protected area, then the N local units of the feature are top-N included. For example, if 3 local units of a feature within a protected area are with ranks of 3?2 (3 is the highest) and other local units are with ranks of 2 or lower, then the set is said to be top-3 included. - target In SecSel, the targets for individual features are equated to the number of highly ranked units in a protected area. If the target is N for a given feature, the top-N of the units of the feature should be included. In SecSel, a set of several local units with low ranks for a biodiversity feature is not a substitute for a single unit with a high rank. [Data file of values of local unit] To run SecSel, a data file of local units of all features to be considered in all sites is required. The file records the value of each feature in each site. The first line is the header, and the first should be 'site', followed by the name of each feature. Each line below the second line corresponds to each site. Each line contains the site name followed by the value of each feature, separated by tabs. If a feature is present at a site, it is assumed to have a value greater than 0. The value can be either an integer or a real number. The provided sample file foo_local_units.txt contains values of local units of 8 features distributed among 400 sites. There are three rank levels, the highest being 3. The first three digits of the site name represent the x coordinate of the site and the latter three represent the y coordinate. [parameter file] In the parameter file, you can specify the name of the data file to be analyzed, set the target for conservation/use, and other settings related to the control of SecSel's operation. The parameter file is a text file. Each line should contain the parameter name and the value to be set for the parameter, separated by a tab. Blank lines and anything after # will be ignored. The following is a description of the minimum settings. See also the "parameters.txt" file included in "test_dataset.zip" for a description of minimal settings. See also "readme_more.txt" and other data files in "test_dataset.zip". - local_units_file The name of the file which contains values of local units. - output_file_base The base string for the name of the resulting output file; SecSel outputs multiple files, and the names of those files begin with this string. SecSel can automatically make multiple runs, and the name of a result file for each attempt will be xxxx_NNN_PA.txt (where xxxx is the specified base string and NNN is the serial number of the run). A summary file of the results of multiple runs is also generated, and its file name is xxxx_sum.txt. - default_top_n Default value of the preservation/use target. For any feature that does not have a separate target in the target file (top_n_file), this value is set as the target. SecSel performs a site selection so that the protected area includes the local units from the highest-rated local unit to this number of targets. See readme_more.txt for details of the target file. - n_run Number of runs of site selection. If not specified, single run is made. If there are multiple equally effective sites, the result of each run can differ because Secsel randomly selected a site among them in the selection of sites. Therefore, we can repeat the process a sufficient number of times and choose a suitable one among them. We can also summarize the results of many runs and pay attention to the frequency with which each site is included in the selected area in multiple runs. [Output files of site selection] As described in the Execution Test section, if you enter the following command at a command prompt or terminal, python run_secsel_example.py parameters.txt then ten selections are repeated according to the settings in the parameter file parameters.txt, and each result is recorded in foo-01_PA.txt, foo-02_PA.txt, ... foo-10_PA.txt. In addition, their summary results are recorded in foo_sum.txt. foo ’is the value (string) of output_file_base set in the parameter file. - Output files for each run Following the header line, the information about the site is recorded in the order of selection. The first column is the site name, and the next column is the order in which they were selected (starting at 1. If there are pre-preserved sites, the order of those sites is labeled as 0). More detailed information can also be output by setting the output format in the parameter file. - Summary file The file summarizes results of multiple runs. Following the header line, the information about the selected sites is recorded in the order of times selected. The first column is the site name, and the next column is the times the site is selected in the replicated runs. More detailed information can also be output by setting the output format in the parameter file. [Appendix: visualizing the results] You can graphically view the result of each run using the provided script map_results.py. Example: visualization of the file created by the first run of the execution test If you enter the following command, python map_results.py foo-01_PA.txt a map pops up, which show the sites selected as a protected area in the first run. If you close the pop-up window, the cursor returns to the command prompt. map_results.py also generates a png file of the map. And if you enter the following, python map_results.py foo_sum.txt you will see a color-coded map with the number of selections for each site in 10 trials. map_results.py determines which type of map to generate by the name of the data file given.