Welcome to SETLyze’s documentation!¶

Data Collection¶

First let’s have a look at how the data for the SETL project is being collected. When the SETL plates are checked, each plate is first carefully pulled out of the water and then photographed. This is done by a standard procedure described on the ANEMOON foundation’s website. First an overview photograph is taken of each plate. Then some more detailed photographs are taken of the species that grow on each plate. Indivdual plates are recognized by their tags. The pictures are then carefully analyzed. For each plate the SETL-monitoring form is filled in. For each species the absence or presence, abundance and area cover are filled in. For this, a 5x5 grid is digitally applied over the photograph (SETL plate with digitally applied grid). For each species the presence or absence on each of the 25 plate surfaces are filled in and saved to the database.

SETL plate with digitally applied grid

Each record in the database contains a species ID, a plate ID, and the 25 plate surfaces. The species ID links to the species that was found on the plate. The plate ID links to the plate on which that species was found. The plate ID is also linked to the location where this plate was deployed. The 25 plate surfaces (“spots”) are stored in each record as booleans (meaning they can have a value of True or False). The value 1 (True) for a spot means that the species in question was present on that spot of the plate. The value 0 (False) means that the species was absent from that spot.

With 25 spots x 2500 records = 625000+ booleans for the presence/absence of species, automatic methods of analyzing this data are required. Hence SETLyze was developed, a tool for analyzing the settlement of species on SETL plates.

Definition List¶

This part of the user manual describes some terminology often used throughout the application and this manual.

Intra specific

Within a single species.

Inter specific

Between two different species.

Plate area

The defined area on a SETL plate. By default the SETL plate is divided in four plate areas (A, B, C and D):

Default plate areas

Plate areas can be customized during an analysis, see Define Plate Areas dialog.

Positive spot

Each record in the SETL database contains data for each of the 25 spots on a SETL plate. The spots are stored as booleans, meaning they can have two values; 1 (True) means that the species was present on that spot, 0 (False) means that the species was absent on that spot. A spot is “positive” if the spot value is 1 or True. Each record can thus have up to 25 positive spots.

SETL plate

In the SETL project standardized PVC-plates are used to detect invasive species and other fouling community organisms. In this project 14x14 cm PVC-plates are hung 1 meter below the water surface, and refreshed and checked for species at least every three months.

Spot

To analyze SETL plates, photographs of the plates are taken. The photographs are then analyzed on the computer by applying a 5x5 grid to the photographs. This divides the SETL plate into 25 equal surface areas (see SETL plate with digitally applied grid). Each of the 25 surface areas are called “spots”. Species are scored for presence/absence for each of the 25 spots on each SETL plate, and the data is stored in the SETL database in the form of records. So each SETL record in the database contains presence/absence data of one species for all 25 spots on a SETL plate.

Spot distance

Spot distances are the distances between positive spots on a SETL plate. The spot distances are calculated from observed and expected positive spots data and are used to define whether species attract or repel.

Observed spot distances (intra specific)

All possible distances between the spots on each plate are calculated using the Pythagorean theorem. Consider the case of species A and the following plate:

Spot distances on SETL plate (intra specific)

As you can see from the figure, three positive spots results in three spot distances (a, b and c). The distance from one spot to the next by moving horizontally or vertically is defined as 1. The distances from the figure are calculated as follows:

This is done for all plates of an analysis. Note that there can be no distance 0, in contrast to inter specific spot distances (see below).

Observed spot distances (inter specific)

To obtain spot distances for analyses where two species are involved, first the plate records are collected that contain both of the selected species. Then all possible spot distances are calculated between the two species. The following figure shows an example with positive spots for two species (A and B) and all possible spot distnaces.

Spot distances on SETL plate (inter specific)

In the above figure, the distances are calculated the same way as for intra specific spot distances. Note however that only inter specific distances are calculated (distances between two different species). This also makes it possible to have a distance of 0 as visualized in the next figure.

Spot distances on SETL plate (inter specific)

The distances for this figure are calculated as follows:

Expected spot distances

The expected spot distances are calculated by generating a copy of each plate record matching the species selection. Each copy has the same number of positive spots as its original, except the positive spots are placed randomly at the plates. Then the spot distances are calculated the same way as for the observed spot distances. This means that the resulting list of expected spot distances has the same length as the observed spot distances.

Analysis Selection dialog¶

Analysis Selection dialog

The analysis selection dialog is the first dialog you see when SETLyze is started. It allows the user to select an analysis to perform on SETL data. The user can select one of the analyses in the list and click on the OK button to start the analysis. Clicking the Quit button closes the application.

After pressing the OK button, two things can happen. If no SETL data was found on the user’s computer, SETLyze automatically tries to load SETL locations and species data from the SETL database server. This requires a direct connection with the SETL database server. A progress dialog is shown while the data is being loaded. If connecting to the database server fails, SETLyze continues without data. Since the database server has not been implemented yet, no data will be loaded.

If SETL data is found on the user’s computer, an information dialog is displayed telling the user that existing data is being loaded.

Clicking the About button shows SETLyze’s About dialog. The About dialog shows general information about SETLyze; its version number, license information, a link to the GiMaRIS website, the application developers, and contact information.

Clicking the Preferences button loads the Preferences dialog.

Batch Mode dialog¶

Batch Mode dialog

Selecting “Batch mode” in the Analysis Selection dialog brings up the Batch Mode dialog. This dialog allows you to start an analysis in batch mode. In batch mode, the selected analysis is repeated for each species in a species selection (or each inter species combination for analysis “Attraction between Species”). When multiple species are selected the analysis is repeated for each species separately and the results are displayed in a Summary Report. The summary report only displays the species that had significant results.

Preferences dialog¶

Preferences dialog

The preferences dialog allows you to change SETLyze’s settings. Settings set here are saved to a configuration file in the user’s home directory (~/.setlyze/setlyze.cfg). The following settings can be changed:

Alpha level (α) for statistical tests

Sets the alpha level. The alpha level must be a number between 0 and 1. The default value 0.05 means an alpha level of 5%.

This alpha level is translated to a confidence level with the formula . This confidence level is used for some statistical tests to calculate the confidence interval. At this moment this is just the t-test (not used in any analysis at this point).

The alpha level is also used to determine if a P-value returned by statistical tests is considered significant. The P-value is considered significant if the P-value is equal or less than the alpha level.

Number of repeats for statistical tests

Sets the number of repeats to perform on some statistical tests. Some statistical tests used in SETLyze use expected values that are randomly generated. This means you can’t draw a solid conclusion from the result of just one test. There is a change that the found result was a coincidence. To account for this, these test are repeated a number of times. The default value is 20 repeats. This value is very low, but good enough for testing purposes. When you need to draw solid conclusions, this value needs to be set to a higher number.

Number of concurrent processes for batch mode

Batch mode for analyses are parallelized which means that multiple analyzes can be executed in parallel. The value set here corresponds to the number of concurrent processes that will execute analyses. The higher the number, the faster a batch analysis will complete. The number of processes must be at least 1 and no more than the number of CPUs. The default value of this option equals to 90% of the available CPUs.

Locations Selection dialog¶

Locations Selection dialog

The locations selection dialog shows a list of all SETL locations. This dialog allows you to select locations from which you want to select species. The Species Selection dialog (displayed after clicking the Continue button) will only display the species that were recorded in the selected locations. Subsequently this means that only the SETL records that match both the locations and species selection will be used for the analysis, as each SETL record is bound to a species and a SETL plate from a specific location.

The Change Data Source button opens the Load Data dialog. This dialog allows you to load new SETL data. After doing so, the locations selection dialog is automatically updated with the new data.

The Back button allows you to go back to the previous dialog. This can be useful when you want to correct a choice you made in a previous dialog.

The Continue button saves the selection, closes the dialog, and shows the next dialog.

Species Selection dialog¶

Species Selection dialog

The species selection dialog shows a list of all SETL species that were found in the selected SETL locations. This dialog allows you to select the species to be included in the analysis. Only the SETL records that match both the locations and species selection will be used for the analysis.

It is possible to select more than one species (see Making a selection). Selecting more than one species in a single species selection dialog means that the selected species are threated as one species for the analysis. In batch mode however, the analysis is repeated for each of the selected species.

If the selected analysis requires two or more separate species selections (e.g. two species are compared), it will display the selection dialog multiple times. In this case, the header of the selection dialog will say “First Species Selection”, “Second Species Selection”, etc.

The Back button allows you to go back to the previous dialog. This can be useful when you want to correct a choice you made in a previous dialog.

The Continue button saves the selection, closes the dialog, and shows the next dialog.

Load Data dialog¶

Load Data dialog

The Load Data dialog allows you to load SETL data into SETLyze. Two data sources are supported:

• Text CSV (*.csv, *.txt) files exported from the Microsoft Access SETL database. The CSV files need to be exported by Microsoft Access, one file for each of the four tables: SETL_localities, SETL_plates, SETL_records, and SETL_species. The section Exporting SETL data from the Access database describes how to export these files.
• Excel 97/2000/XP/2003 (*.xls) files exported from the Microsoft Access SETL database. One file for each of the four tables: SETL_localities, SETL_plates, SETL_records, and SETL_species. Microsoft Access by default includes a header row in the exported XLS files. The header row must be removed before importing into SETLyze.

After selecting all four data files files, press the OK button to load the SETL data from these files. A progress dialog is shown while the data is being loaded. Once the data has been loaded, the Locations Selection dialog will be updated with the new data.

Define Plate Areas dialog¶

Define Plate Areas dialog

This dialog allows you to define the plate areas for analysis “Spot Preference”. By default, the SETL plate is divided in four plate areas: A, B, C and D. This dialog allows you to combine these areas by changing the area definitions. Combining areas means that the combined areas are treated as a single plate area. One must define at least two plate areas.

The user defined plate areas are only used for the Chi-squared test. In any case the Wilcoxon test will analyze the plate areas A, B, C, D, A+B, C+D, A+B+C and B+C+D.

Below is a schematic SETL plate with a grid. By default the plate is divided in four plate areas (A, B, C and D),

Default plate areas

But sometimes it’s useful to combine plate areas. So if one decides to combine areas A and B, the selection could be changed as follows,

Combined plate areas selection

And the resulting plate areas definition would look something like this,

Plate areas A and B combined.

This would result in three plate areas. Analysis “Spot Preference” would then determine if the selected species has a preference for either of the three plate areas.

The names of the plate areas (area 1, area 2, ...) do not have a special meaning. It is simply used internally by the application to distinguish between plate areas. These area names are also used in the analysis report to distinguish between the plate areas.

The Back button allows you to go back to the previous dialog. This can be useful when you want to correct a choice you made in a previous dialog.

The Continue button saves the selection, closes the dialog, and shows the next dialog.

Analysis Report dialog¶

Analysis Report dialog

The analysis report dialog shows the results for an analysis. The dialog consists of the results frame and a toolbar on top. The toolbar holds a number of buttons. Hover your mouse pointer over the buttons to reveal a tooltip which explains the button’s action. Some buttons are explained below:

Save

The “Save” button allows you to save the report to a file. Clicking this button first shows a File Save dialog which allows you to select a target directory and filename. One file type is supported:

• reStructuredText (*.rst) - Plain text files in an easy-to-read markup syntax. One can use Docutils to convert reStructuredText files into useful formats, such as HTML, LaTeX, man-pages, open-document or XML.

Save All

The “Save All” button is only enabled in batch mode and allows you to export the reports of the individual analyses. Clicking the “Save” button in batch mode only saves the Summary Report which is based on the individual reports.

Repeat

The “Repeat” button can be used to repeat an analysis with different parameters. Clicking this button will open a dialog which shows the same parameters available in the Preferences dialog. So one can, for example, quickly repeat the analysis with a different number of repeats.

The report dialog can display two types of reports:

• Standard Report: When running an analysis in standard mode (not in batch mode) the report is divided into sections. There is a section for each statistical test that was performed.
• Summary Report: When running an analysis in batch mode the report will be a summary of all standard reports that were generated. This report will show less details than a standard report.

Both types of reports will be explained below.

Record Grouping¶

SETLyze performs statistical tests to determine the significance of results. The key statistical tests used to determine significance are the Wilcoxon rank-sum test and Pearson’s Chi-squared test. The tests are performed on records data that match the locations and species selection. It is however not a good idea to just perform the test on all matching records. For this reason the matching records are first grouped by a specific property. The tests are then performed on each group.

Two methods for grouping records have been implemented. One is by positive spots number, and the other is by positive spots ratio. We’ll describe each grouping method below.

Export to CSV files¶

This section describes how to export the SETL data from the Microsoft Access database to CSV files.

1. Open the SETL database file (*.mdb) in Microsoft Access. You’ll see four tables in the left column: SETL_localities, SETL_plates, SETL_records and SETL_species.
2. To export a table, right-click on it to open the drop menu. From the menu select Export > Text file. Then give the filename of the output file. Make sure to include the table name in the filename (e.g. setl_localities.csv for the “SETL_localities” table). Uncheck all other options and press OK.
3. In the next dialog that appears select the option that separates fields with a character. The separator character must be a semicolon (”;”). If it’s not, change it by clicking the Advanced button. Then click Finish to export the data to a CSV file.
4. Repeat steps 2 and 3 for all tables.
5. You should end up with four files, one CSV file for each table. Put these files in one folder.

Export to Excel files¶

The database tables can also be exported to Excel files. Only the import of Excel 97/2000/XP/2003 (*.xls) files are supported by SETLyze, so be sure to select the right format.

Obtaining the source code¶

The source code for SETLyze is currently hosted on GitHub. The project page can be found at the following URL: https://github.com/figure002/setlyze

The source code is version controlled with Git. You’ll need to install Git before you can start working on SETLyze. Go to http://git-scm.com/ to get started with Git.

If you are new to using Git, there is a well written online book Pro Git which explains everything you need to know about using Git. At least read through the Getting Started section.

Once you have Git installed and properly setup, you can obtain a copy of the source code for SETLyze with the following command

git clone git://github.com/figure002/setlyze.git

Navigating the SETLyze folder¶

The key files in SETLyze’s root folder are:

src/setlyze/

This is SETLyze’s main code base. This package folder contains all of SETLyze’s modules. This is the folder where you’ll be editing most Python source files for SETLyze.

src/setlyze.pyw

This is SETLyze’s executable. This is what you’ll run to start SETLyze.

src/setlyze/docs/html/

This folder contains the documentation for SETLyze. This includes the User Manual and the Developer Guide. You can view the manual by (double) clicking index.html. This should open the documentation in your web browser.

src/doc-src/

This folder contains the files used to build the documentation. This is done using Sphinx. Some parts of the documentation are from .rst-files within this folder, others are extracted from the documentation strings within the program source code.

README.md

This text file contains a short description of the program and directs you to other documentation.

COPYING

This text file contains the license for SETLyze. SETLyze is released under the GNU General Public License version 3.

INSTALL

Text file with installation instructions for SETLyze.

Technical Design¶

SETLyze comes with a Technical Design; a visual representation of SETLyze’s design parts (functions/classes/GUI’s) interconnected by arrows representing the application’s functions and work flow. All design parts are numbered. The same numbers can be found in the SETLyze’s source code. This means that the different design parts of the Technical Design can be easily linked to the corresponding source code.

The Technical Design provides an easy to understand overview of the application for users, but is also of great value to developers. It makes it easier to get a basic understanding of how the application works by looking at the Technical Design. If the developer is interested in a specific part of the application, he or she can easily navigate to the corresponding description and source code by the reference numbers used in the Technical Design.

Both the descriptions and source codes for the design parts in the Technical Design are browsable using this documentation. Read the “Design Parts” section below.

CREATE TABLE setl_records
(
    rec_id              SERIAL,
    rec_pla_id          INTEGER NOT NULL,
    rec_spe_id          INTEGER NOT NULL,
    rec_unknown         BOOLEAN,
    rec_o               BOOLEAN,
    rec_r               BOOLEAN,
    rec_c               BOOLEAN,
    rec_a               BOOLEAN,
    rec_e               BOOLEAN,
    rec_sur_unknown     BOOLEAN,
    rec_sur1            BOOLEAN,
    rec_sur2            BOOLEAN,
    rec_sur3            BOOLEAN,
    rec_sur4            BOOLEAN,
    rec_sur5            BOOLEAN,
    rec_sur6            BOOLEAN,
    rec_sur7            BOOLEAN,
    rec_sur8            BOOLEAN,
    rec_sur9            BOOLEAN,
    rec_sur10           BOOLEAN,
    rec_sur11           BOOLEAN,
    rec_sur12           BOOLEAN,
    rec_sur13           BOOLEAN,
    rec_sur14           BOOLEAN,
    rec_sur15           BOOLEAN,
    rec_sur16           BOOLEAN,
    rec_sur17           BOOLEAN,
    rec_sur18           BOOLEAN,
    rec_sur19           BOOLEAN,
    rec_sur20           BOOLEAN,
    rec_sur21           BOOLEAN,
    rec_sur22           BOOLEAN,
    rec_sur23           BOOLEAN,
    rec_sur24           BOOLEAN,
    rec_sur25           BOOLEAN,
    rec_1st             BOOLEAN,
    rec_2nd             BOOLEAN,
    rec_v               BOOLEAN,
    rec_photo_nrs       VARCHAR(100),
    rec_remarks         VARCHAR(100),

    CONSTRAINT rec_id_pk PRIMARY KEY (rec_id),
    CONSTRAINT rec_pla_id_fk FOREIGN KEY (rec_pla_id)
        REFERENCES setl_plates (pla_id)
        ON DELETE NO ACTION
        ON UPDATE NO ACTION,
    CONSTRAINT rec_spe_id_fk FOREIGN KEY (rec_spe_id)
        REFERENCES setl_species (spe_id)
        ON DELETE NO ACTION
        ON UPDATE NO ACTION
);

CREATE TABLE setl_species
(
    spe_id                    SERIAL,
    spe_name_venacular        VARCHAR(100) UNIQUE,
    spe_name_latin            VARCHAR(100) NOT NULL UNIQUE,
    spe_invasive_in_nl        BOOLEAN,
    spe_description           VARCHAR(300),
    spe_remarks               VARCHAR(160),
    spe_picture               OID,

    CONSTRAINT spe_id_pk PRIMARY KEY (spe_id)
);

CREATE TABLE setl_localities
(
    loc_id              SERIAL,
    loc_name            VARCHAR(100) NOT NULL UNIQUE,
    loc_nr              INTEGER,
    loc_coordinates     VARCHAR(100),
    loc_description     VARCHAR(300),

    CONSTRAINT loc_id_pk PRIMARY KEY (loc_id)
);

CREATE TABLE species
(
    spe_id INTEGER PRIMARY KEY,
    spe_name_venacular VARCHAR,
    spe_name_latin VARCHAR,
    spe_invasive_in_nl INTEGER,
    spe_description VARCHAR,
    spe_remarks VARCHAR
);

CREATE TABLE localities
(
    loc_id INTEGER PRIMARY KEY,
    loc_name VARCHAR,
    loc_nr VARCHAR,
    loc_coordinates VARCHAR,
    loc_description VARCHAR
);

CREATE TABLE records
(
    rec_id INTEGER PRIMARY KEY,
    rec_pla_id INTEGER,
    rec_spe_id INTEGER,
    rec_unknown INTEGER,
    rec_o INTEGER,
    rec_r INTEGER,
    rec_c INTEGER,
    rec_a INTEGER,
    rec_e INTEGER,
    rec_sur_unknown INTEGER,
    rec_sur1 INTEGER,
    rec_sur2 INTEGER,
    rec_sur3 INTEGER,
    rec_sur4 INTEGER,
    rec_sur5 INTEGER,
    rec_sur6 INTEGER,
    rec_sur7 INTEGER,
    rec_sur8 INTEGER,
    rec_sur9 INTEGER,
    rec_sur10 INTEGER,
    rec_sur11 INTEGER,
    rec_sur12 INTEGER,
    rec_sur13 INTEGER,
    rec_sur14 INTEGER,
    rec_sur15 INTEGER,
    rec_sur16 INTEGER,
    rec_sur17 INTEGER,
    rec_sur18 INTEGER,
    rec_sur19 INTEGER,
    rec_sur20 INTEGER,
    rec_sur21 INTEGER,
    rec_sur22 INTEGER,
    rec_sur23 INTEGER,
    rec_sur24 INTEGER,
    rec_sur25 INTEGER,
    rec_1st INTEGER,
    rec_2nd INTEGER,
    rec_v INTEGER
);

setlyze.config.cfg.get('locations-selection', slot=int)

setlyze.config.cfg.set('locations-selection', list, slot=int)

setlyze.config.cfg.get('species-selection', slot=int)

setlyze.config.cfg.set('species-selection', list, slot=int)

CREATE TABLE species_spots_1
(
    id INTEGER PRIMARY KEY,
    rec_pla_id INTEGER,
    rec_sur1 INTEGER,
    rec_sur2 INTEGER,
    rec_sur3 INTEGER,
    rec_sur4 INTEGER,
    rec_sur5 INTEGER,
    rec_sur6 INTEGER,
    rec_sur7 INTEGER,
    rec_sur8 INTEGER,
    rec_sur9 INTEGER,
    rec_sur10 INTEGER,
    rec_sur11 INTEGER,
    rec_sur12 INTEGER,
    rec_sur13 INTEGER,
    rec_sur14 INTEGER,
    rec_sur15 INTEGER,
    rec_sur16 INTEGER,
    rec_sur17 INTEGER,
    rec_sur18 INTEGER,
    rec_sur19 INTEGER,
    rec_sur20 INTEGER,
    rec_sur21 INTEGER,
    rec_sur22 INTEGER,
    rec_sur23 INTEGER,
    rec_sur24 INTEGER,
    rec_sur25 INTEGER
);

CREATE TABLE species_spots_2
(
    id INTEGER PRIMARY KEY,
    rec_pla_id INTEGER,
    rec_sur1 INTEGER,
    rec_sur2 INTEGER,
    rec_sur3 INTEGER,
    rec_sur4 INTEGER,
    rec_sur5 INTEGER,
    rec_sur6 INTEGER,
    rec_sur7 INTEGER,
    rec_sur8 INTEGER,
    rec_sur9 INTEGER,
    rec_sur10 INTEGER,
    rec_sur11 INTEGER,
    rec_sur12 INTEGER,
    rec_sur13 INTEGER,
    rec_sur14 INTEGER,
    rec_sur15 INTEGER,
    rec_sur16 INTEGER,
    rec_sur17 INTEGER,
    rec_sur18 INTEGER,
    rec_sur19 INTEGER,
    rec_sur20 INTEGER,
    rec_sur21 INTEGER,
    rec_sur22 INTEGER,
    rec_sur23 INTEGER,
    rec_sur24 INTEGER,
    rec_sur25 INTEGER
);

CREATE TABLE spot_distances_observed
(
    id INTEGER PRIMARY KEY,
    rec_pla_id INTEGER,
    distance REAL
);

CREATE TABLE spot_distances_expected
(
    id INTEGER PRIMARY KEY,
    rec_pla_id INTEGER,
    distance REAL
);

CREATE TABLE info
(
    id INTEGER PRIMARY KEY,
    name VARCHAR,
    value VARCHAR
);

cursor.execute( "INSERT INTO info VALUES (null, 'source', ?)", [setlyze.config.cfg.get('data-source')] )

cursor.execute("INSERT INTO info VALUES (null, 'version', ?)", [db_version])

cursor.execute( "INSERT INTO info VALUES (null, 'date', date('now'))" )

CREATE TABLE setl_plates
(
    pla_id                  SERIAL,
    pla_loc_id              INTEGER NOT NULL,
    pla_setl_coordinator    VARCHAR(100),
    pla_nr                  VARCHAR(100),
    pla_deployment_date     TIMESTAMP,
    pla_retrieval_date      TIMESTAMP,
    pla_water_temperature   VARCHAR(100),
    pla_salinity            VARCHAR(100),
    pla_visibility          VARCHAR(100),
    pla_remarks             VARCHAR(300),

    CONSTRAINT pla_id_pk PRIMARY KEY (pla_id),
    CONSTRAINT pla_loc_id_fk FOREIGN KEY (pla_loc_id)
        REFERENCES setl_localities (loc_id)
        ON DELETE NO ACTION
        ON UPDATE NO ACTION
);

CREATE TABLE plates
(
    pla_id INTEGER PRIMARY KEY,
    pla_loc_id INTEGER,
    pla_setl_coordinator VARCHAR,
    pla_nr VARCHAR,
    pla_deployment_date TEXT,
    pla_retrieval_date TEXT,
    pla_water_temperature VARCHAR,
    pla_salinity VARCHAR,
    pla_visibility VARCHAR,
    pla_remarks VARCHAR
);

setlyze.config.cfg.get('analysis-report')

setlyze.config.cfg.set('analysis-report', value)

LOC_id;LOC_name;LOC_nr;LOC_coordinates;LOC_description

SPE_id;SPE_name_venacular;SPE_name_latin;SPE_invasive_in_NL;SPE_description;SPE_remarks;SPE_picture

PLA_id;PLA_LOC_id;PLA_SETL_coordinator;PLA_nr;PLA_deployment_date;PLA_retrieval_date;PLA_water_temperature;PLA_salinity;PLA_visibility;PLA_remarks

REC_id;REC_PLA_id;REC_SPE_id;REC_?;REC_O;REC_R;REC_C;REC_A;REC_E;REC_sur?;REC_sur1;REC_sur2;REC_sur3;REC_sur4;REC_sur5;REC_sur6;REC_sur7;REC_sur8;REC_sur9;REC_sur10;REC_sur11;REC_sur12;REC_sur13;REC_sur14;REC_sur15;REC_sur16;REC_sur17;REC_sur18;REC_sur19;REC_sur20;REC_sur21;REC_sur22;REC_sur23;REC_sur24;REC_sur25;REC_1st;REC_2nd;REC_V;REC_photo_nrs;REC_remarks

setlyze.config.cfg.get('data-source')

setlyze.config.cfg.set('data-source', value)

CREATE TABLE spot_distances
(
    id INTEGER PRIMARY KEY,
    delta_x INTEGER,
    delta_y INTEGER,
    distance REAL
);

{
'area1': list,
'area2': list,
'area3': list,
'area4': list
}

{
'area1': ['A'],
'area2': ['B'],
'area3': ['C'],
'area4': ['D']
}

{
'area1': ['A', 'B'],
'area3': ['C'],
'area4': ['D']
}

setlyze.config.cfg.get('plate-areas-definition')

setlyze.config.cfg.set('plate-areas-definition', value)

{
'area4': 52,
'area1': 276,
'area2': 751,
'area3': 457
}

{
'area4': 61.439999999999998,
'area1': 245.75999999999999,
'area2': 737.27999999999997,
'area3': 491.51999999999998
}

CREATE TABLE plate_spot_totals
(
    pla_id INTEGER PRIMARY KEY,
    n_spots_a INTEGER,
    n_spots_b INTEGER
);

CREATE TABLE plate_area_totals_observed (
    pla_id INTEGER PRIMARY KEY,
    area_a INTEGER,
    area_b INTEGER,
    area_c INTEGER,
    area_d INTEGER
);

CREATE TABLE plate_area_totals_expected (
    pla_id INTEGER PRIMARY KEY,
    area_a INTEGER,
    area_b INTEGER,
    area_c INTEGER,
    area_d INTEGER
);

Navigating the SETLyze Code Base¶

SETLyze’s many functions and classes are stored in different modules. Classes and functions with similar functions are placed in the same module.

Below is an overview of all modules for SETLyze. You can click on a module to get a description of that module and all its elements. You can even view the source-code for a specific function or class by clicking the [source] link on the right side of the description.

Code layout¶

Please write PEP-8 compliant code.

One often-missed requirement is that the first line of docstrings should be a self-contained one-sentence summary.

We use 4 space indents for blocks, and never use tab characters.

Trailing white space should be avoided, but is allowed. If possible, configure your text editor to automatically remove trailing spaces and tabs upon saving.

Unix style newlines (LF) are used.

Each file must have a newline at the end of it.

Lines should be no more than 79 characters if at all possible. Use a text editor that has some kind of long line marker indicating the 79 characters boundary. Lines that continue a long statement may be indented in either of two ways:

within the parenthesis or other character that opens the block, e.g.:

my_long_method(arg1,
               arg2,
               arg3)

or indented by four spaces:

my_long_method(arg1,
    arg2,
    arg3)

The first is considered clearer by some people; however it can be a bit harder to maintain (e.g. when the method name changes), and it does not work well if the relevant parenthesis is already far to the right. Avoid this:

self.legbone.kneebone.shinbone.toebone.shake_it(one,
                                                two,
                                                three)

but rather

self.legbone.kneebone.shinbone.toebone.shake_it(one,
    two,
    three)

or

self.legbone.kneebone.shinbone.toebone.shake_it(
    one, two, three)

For long lists, we like to add a trailing comma and put the closing character on the following line. This makes it easier to add new items in the future:

from setlyze.std import (
    uniqify,
    median,
    distance,
    )

There should be spaces between function parameters, but not between the keyword name and the value:

call(1, 3, cheese=quark)

Module Imports¶

• Imports should be done at the top-level of the file, unless there is a strong reason to have them lazily loaded when a particular function runs. Import statements have a cost, so try to make sure they don’t run inside hot functions.

Naming¶

Functions, methods or members that are relatively private are given a leading underscore prefix.

We prefer class names to be concatenated capital words (TestCase) and variables, methods and functions to be lowercase words joined by underscores (revision_id, get_revision).

For the purposes of naming some names are treated as single compound words: “filename”, “revno”.

Consider naming classes as nouns and functions/methods as verbs.

Try to avoid using abbreviations in names, because there can be inconsistency if other people use the full name.

Standard Names¶

revision_id not rev_id or revid

Functions that transform one thing to another should be named x_to_y (not x2y as occurs in some old code.)

Event and Signal Handling¶

A large part of SETLyze is controlled with signals and signal handlers. To emit custom application signals we use setlyze.std.sender.emit(). And to connect a signal to a signal handler, we use setlyze.std.sender.connect(). When signal handlers are no longer needed, use setlyze.std.sender.disconnect() to disconnect the handler from the signal. Calling setlyze.std.sender.disconnect() should generally be done when the instance that called setlyze.std.sender.connect() is destroyed.

License Statement¶

SETLyze is released under the GNU General Public License version 3. Each file that’s part of SETLyze must have the copyright notice and copying permission statement included at the top of the file after the encoding declaration. So the top of each file should look like this:

#!/usr/bin/env python
# -*- coding: utf-8 -*-
#
#  Copyright 2010, GiMaRIS <info@gimaris.com>
#
#  This file is part of SETLyze - A tool for analyzing the settlement
#  of species on SETL plates.
#
#  SETLyze is free software: you can redistribute it and/or modify
#  it under the terms of the GNU General Public License as published by
#  the Free Software Foundation, either version 3 of the License, or
#  (at your option) any later version.
#
#  SETLyze is distributed in the hope that it will be useful,
#  but WITHOUT ANY WARRANTY; without even the implied warranty of
#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
#  GNU General Public License for more details.
#
#  You should have received a copy of the GNU General Public License
#  along with this program.  If not, see <http://www.gnu.org/licenses/>.

Documentation¶

The content of this documentation is property of their authors. Some contents of this documentation was produced elswhere and reproduced here with permission.

You are welcome to display on your computer, download and print pages from this documentation provided the content is only used for personal, educational and non-commercial use. You must retain copyright and other notices on any copies or printouts you make. The content of this documentation is subject to the GNU General Public Licence (“GPL”) unless otherwise stated.

SETLyze¶

SETLyze is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

SETLyze is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with the program. If not, see http://www.gnu.org/licenses/.