Configuring your Ensembl species

Species ini files

The species configuration (database names, etc.) is kept in the conf/ini_files directory as an "ini" file. There is a generic file called DEFAULTS.ini which holds default values for all the species. (This is simply to save having to make the same setting in multiple species ini files.) There needs to be a species-specific .ini file for each species you want to display on your Ensembl website (e.g. Homo_sapiens.ini). You can override settings in DEFAULTS.ini by redefining the setting in a particular species' ini file. The MULTI.ini contains multi-species settings. It has database connection information for the Compara and Mart databases.

To create a new species-specific ini file, copy, rename and modify the template file in public-plugins/mirror/conf/ini-files/Genus_species.ini.

Customising your species list

The default species for Ensembl are listed in this file:

public-plugins/ensembl/conf/SiteDefs.pm

in %__species_aliases. These are automatically imported into the main conf/SiteDefs::ENSEMBL_SPECIES_ALIASES. In this distribution all the default species are enabled. (See below on how to customise your own list).

The keys of the hash (the species names on the left hand side) define the list of valid species for this website. The values of the hash (the aliases on the right) can be used in URLs instead of the longer species names. i.e.

http://my.ensembl.site/mouse/contigview

is identical to

http://my.ensembl.site/Mus_musculus/contigview

To configure a species it has to have an appropriately-named .ini file in the conf/ini_files directory and to be present as in the %__species_aliases as shown below:

sub update_conf {
  $SiteDefs::ENSEMBL_PERL_SPECIES  = 'Homo_sapiens'; # Default species
  $SiteDefs::__species_aliases{ 'Bos_taurus'      } = [qw(bt cow moo)];
  $SiteDefs::__species_aliases{ 'Canis_familiaris'} = [qw(cf dog)];
  $SiteDefs::__species_aliases{ 'Homo_sapiens'    } = [qw(hs human man default)];
}

To overwrite the default species and customise your own species list add lines (described below) to the "update_conf" method in your mirror plugin: public-plugins/mirror/conf/SiteDefs.pm.

  1. To delete a species:
        delete( $SiteDefs::__species_aliases{'Bos_taurus'} );
  2. To add a new species:
        $SiteDefs::__species_aliases{'New_species'} = [qw(ns new)];
  3. To add an additional alias to a species:
        push @{$SiteDefs::__species_aliases{'Pan_troglodytes'}}, qw(chimpanzee);

Remember to create an ini file for each of the species in public-plugins/mirror/conf/ini-files/<Genus_species>.ini. If you put your changes into the public-plugins/mirror directory, they will not be overridden when you next do a cvs update.

You might also want to change $SiteDefs::ENSEMBL_PERL_SPECIES - this is a special alias for URLs of the form http://my.ensembl.site/perl/contigview, for purely historical reasons. It will probably be used in the future to set the default species for multi-species pages/functions.

Once you are happy with your ini files, run the utility script utils/update_webdb.pl, which will update ensembl_website with species information (assembly IDs, etc) for that release. Although not essential for the running of an Ensembl site, this database is used by several static content utilities as well as the news and help pages.

Static content for your species

A new species needs at a minimum, a directory and home page:

If you would like your species home page to match that of the existing Ensembl site, you will need the following:

  1. A subdirectory public-plugins/mirror/htdocs/[Genus_species]/ssi/
  2. An index page copied from a similar species. There are only two variations on the species home page, depending on whether the genome has been assembled into chromosomes or not. Both versions have four smaller HTML files that are placed within the home page using server-side includes; note that you will see errors on the page if these files do not exist. The files are:

The Ensembl home page and site maps

If you have added or deleted species, you will needed to generate new species lists for the home page and new site maps (see below).

If you have added species, you will also need a thumbnail image of the species, for use on the home page and main sitemap. The image must be 40x40px and called thumb_[Genus_species].png. Save it in public-plugins/mirror/htdocs/img/species/

Species lists

As of Release 42, the main species list is generated automatically from config.packed when the site is started. Only the pre species are manually edited - they are listed in /public-plugins/ensembl/htdocs/ssi/species_reorder_footer.html

If you do not wish to have the links to the pre species (and the associated tabs), you can override them as follows (starting from your server root, and creating the destination directory if it doesn't already exist in your mirror plugin):

cp htdocs/ssi/species_reorder* public-plugins/mirror/htdocs/ssi/

Site maps

These are generated quickly and easily by running utils/sitemap.pl. The script uses the SEARCH_LINKS hash from the cached configuration to generate individual species site maps, and also walks the /info directory to produce a tree of links to site documentation.

The script can be invoked with similar flags to homepage.pl, but does not need a release number.

If you have extended Ensembl by adding new views, you can include them in the site map by editing the script - see the inline documentation under 'TO ADD A NEW VIEW'.