III. Setting up the properties file¶

To connect to a MySQL database¶

A MySQL database is recommended for storing extremely large data that may need to be accessed from different computers. CellProfiler can readily create a MySQL database if a database server is available; see the instructions for the ExportToDatabase module for details.

db_type    =  mysql
db_port    =  3306
db_host    =  your host name
db_name    =  your database name
db_user    =  your user name
db_passwd  =  your password

To connect to an SQLite database¶

SQLite is another mode of data storage, in which tables are stored in a large, database-like file on your local computer rather than a database server. This is easier to set up than a full- featured MySQL database and is at least as fast, but it is not a good choice of storage if the data is to be accessed by multiple concurrent connections. This mode of storage also puts a limitation on the number of rules used in the FastGentleBoosting Algorithm in Classifier (see section III.B.5). CellProfiler is able to export data in this format using the ExportToDatabase module.

db_type         =  sqlite
db_sqlite_file  =  path and filename of SQLite db file

To access multiple comma-separated value (.csv) files produced by CellProfiler¶

This mode tells CPA to find your image and object tables in several CSV files produced using CellProfiler’s ExportToDatabase module. In this mode of data storage, you specify the path to the xxx_SETUP.SQL file written by CellProfiler’s ExportToDatabase module (the “xxx” will be the prefix you specified in the ExportToDatabase module settings). CPA will then use this file to find the CSV files produced by ExportToDatabase to create an SQLite database file in your home directory. This could take a long time for larger databases, but only needs to be done once. Note: This feature expects the CSV files to be in the same directory as the SQL file. If they are renamed or moved apart from the SQL file, CPA will not find them and won’t be able to construct your database.

db_type      =  sqlite
db_sql_file  =  path and filename of .SQL file from ExportToDatabase
To access data stored in two CSV files

This mode tells CPA to find your image and object tables in two CSV files. When you run CPA with these settings, it looks for column headers in the first row of each file and inserts the data into an SQLite database file in your home directory. Again, this could take a long time for larger databases, but only needs to be done once.

db_type          =  sqlite
image_csv_file   =  path and filename of image csv
object_csv_file  =  path and filename of object csv

Database table names¶

The following fields identify the image and object tables:

image_table   =  name of the table with one row per image
object_table  =  name of the table with one row per object

Database column names¶

The following fields identify the columns that specify unique image and object numbers:

image_id   =  image_number key column from the image & object table
object_id  =  object_number key column from the object table

The following field (optional) identifies the columns that specify a table number, which is useful in cases where multiple image tables have been manually merged and the image number column is no longer unique:

table_id  =  table_number key column from the image & object tables

The following fields identify the columns in the object table that specify the x and y location of each object within the original image:

cell_x_loc  =  object x-location column from the object table
cell_y_loc  =  object y-location column from the object table

The following fields (optional) identify plate and well columns in your image table and are only required by the PlateMapBrowser tool:

plate_id  =  plate_id column from the image table
well_id   =  well_id column from the image table

Metadata¶

object_name = singular name, plural name

The following field tells PlateMapBrowser what size plates were used. Supported types are 96, 384, 1536, or 5600 (for cell microarrays)

plate_type  =  number of wells

Columns ignored by Classifier¶

The following field (optional) specifies columns in the per-object table that you want Classifier to ignore when finding rules for classifying objects. Classifier automatically ignores columns defined by the table_id, image_id, and object_id fields, as well as any columns that contain non-numeric data. When using this field to specify additional columns to ignore, note that your column names cannot contain commas because commas are used to separate each column name. You can also use regular expressions to refer to a set of column names for Classifier to ignore:

classifier_ignore_columns = column name or regular expression A,
  column name or regular expression B

For example, the following statement will ignore the column named WellID, any columns whose name contains the text Red (case-sensitive), and any columns that end in _Position.

classifier_ignore_columns = WellID, .*Red.*, .*_Position

Classifier default training set¶

The following field (optional) specifies the full path and file name for a training set that Classifier should automatically load when it is launched:

training_set =  your directory/your subdirectory/your file

Area-based scoring¶

The following field (optional) specifies a column in your per-object table that will be summed and reported when scoring with Classifier. You can use this, for example, to report the total area of objects in each class, in addition to the number of objects in each class (which is Classifier’s default output):

area_scoring_column = your alternate column name

Outputting per-object classes¶

The following field (optional) specifies a MySQL table name for Classifier to create in your database when Score All is used. The class name of each object will be written to this table along with image and object IDs so it may be linked back into your existing tables. Warning: If this table name already exists, it will be overwritten:

class_table = your class table name

Checking your tables¶

The following field (optional) tells Classifier whether to check your tables at startup for anomalies such as missing column indices (an index is a database structure that greatly improves the speed of data retrieval) or orphaned objects (objects that do not correspond to an image in the image table). The operation can take up to a minute if your object table is extremely large.

check_tables = yes or no

Different tumbnail size for Image Gallery¶

The following field (optional) tells Image Gallery, how large the thumbnail of the field of view should be. If nothing is set, image_size = image_tile_size

image_size = 200

ImageFilter¶

The following fields (optional) specify a subset of the images in your experiment from which to fetch and score objects in Classifier. Multiple filters can be created by using the format below and replacing ‘XXX’ with a name for the filter. Names can include alphanumeric characters and underscores.

filter_SQL_XXX = SQL select statement that returns image-keys for image you want to include

For example, here is a filter that returns only images from plate 1:

filter_SQL_Plate_1 = SELECT ImageNumber FROM per_image WHERE plate="1"

This example returns only images from with a gene column that starts with CDK:

filter_SQL_CDKs = SELECT ImageNumber FROM per_image WHERE gene REGEXP 'CDK.*'

This example does the same for a database that includes a table_id column TableNumber:

filter_SQL_CDKs = SELECT ImageNumber, TableNumber FROM per_image WHERE gene REGEXP 'CDK.*'

Filters may be created from within CPA by choosing the option “create new filter”. A dialog box will appear that allows you to define filters on the fly. First choose a name for your filter, then choose the column you would like to filter and specify the constraints. For example, below we select lonely those images from well A07:

You may select more than one column for your filter. For example if you would like only those images from well A07 which have more than 10 cells, you would click ‘Add Column’ and specify the filter as such:

When you have completed your filter, click OK. The filter will now be available to you to use in the CPA tools for the remainder of your session.

Groups¶

You can define ways of grouping your image data (for example, when several images represent the same experimental sample), by linking column(s) that identify unique images (the image- key) to another set of columns (the group-key, which may reside in other tables, provided the tables have a common key). Grouping is useful, for example, when you want to aggregate counts for each class of object and their scores on a per-group basis (e.g.: per-well) instead of on a per-image basis when scoring with Classifier. It will also provide new options in the Classifier fetch “from” menu so you can fetch objects from images with specific values for the group columns. Multiple groups can be created by replacing ‘XXX’ with the desired group name:

group_SQL_XXX = MySQL SELECT statement that returns image-key columns followed by group-key columns

For example, if you wanted to be able to group your data by unique plate names, you could define a group called SQL_Plate as follows:

group_SQL_Plate = SELECT ImageNumber, plate FROM per_image

As another example, you could define a way to group unique wells:

group_SQL_Well+Plate = SELECT ImageNumber, plate, well FROM per_image

The previous example, but for a database including a table_id column TableNumber:

group_SQL_Well+Plate = SELECT TableNumber, ImageNumber, plate, well FROM per_image

Image Classification¶

CellProfiler Analyst 2.2 also supports classification directly from image features. To allow this, the biologist has to set the classification type flag to image

classification_type = image