return to tutorials

TUTORIAL: User Settings

September 13, 2021

REFERENCES

BIRCHUserSettings.py documentation

BLHelper.py documentation

Goal: To learn how to modify user-specific settings, including

command prompt
Email address for notifications from long-running jobs
NCBI Entrez API key

0. User Settings vs. System-wide defaults

Each user of a BIRCH installation has their own settings, which override system defaults. This includes several miscellaneous settings, as well as choices of helper applications for opening output from programs.

1. User Settings

Open the BIRCH launcher. One way to launch BIRCH is to type 'birch' at the command line.

Alternatively, click on the BIRCH icon on your desktop

. The BIRCH launcher will appear. To change settings, choose Edit --> Settings.

Initially, the settings menu will appear at right. If you installed BIRCH as the sole user on a personal computer, or as the BIRCH administrator on a multi-user system, the email address will be the one that you entered when installing birch.

If you are one of many users on a multi-user system, the email address will be blank.

IMPORTANT: Setting changes will take effect the next time you launch a shell, or BioLegato application. They will not affect currently-running BioLegato applications.

BIRCH Custom command line prompt

The default BIRCH prompt is a convenience for the user to help them keep track of which machine they are logged into, and the current working directory in a given terminal.

Yes - By default, all users will see the BIRCH default prompt in their terminals.

No - Setting this parameter to No will result in the system default prompt being displayed. The actual prompt displayed may vary from system to system.

If the user has specified a custom prompt in their $HOME/.profile, that prompt will be used instead.

Email address for notifications

This is the email address that BioLegato will use for notifying you when long-running jobs are completed. These might include BLAST searches, installation of BLAST databases, or genome/transcriptome assembly tasks run through blreads. It is probably most convenient to choose an email account that will reach you on your mobile phone.

IMPORTANT: If you plan to do NCBI Entrez keyword searches for sequences, you MUST set an email address. The email address is required by the Entrez Eutils, which are run through blncbi, blnfetch and blpfetch. Since BLAST searches retrieve output using Eutils, in effect, BLAST run though BioLegato also requires an email address.

If you installed BIRCH as the sole user on a personal computer, or as BIRCH administrator on a multiuser system, this address will default to the Administrator's email address that you typed in during the BIRCH install process (ie. getbirch).

If you are one of many users on a multiuser system, this address will initially blank. You must set this address using Edit --> Settings.

HINT: If you are not seeing notifications in your mailbox, check your Spam box. If you find your notifications going to Spam, you need to tell your mail program that these messages are not Spam. It may take several tries before your mailer begins to recognize these as legitimate messages.

NCBI Entrez API Key

It is strongly-advised that all BIRCH users obtain an NCBI Entrez API key and for use by BIRCH when requesting data or services from NCBI.

The NCBI Entrez API key is a unique ID number for NCBI users. The key is mainly needed when making more than 3 data requests per second. Since automated data requests run from BIRCH may occur rapidly, this could occur more often than you might think
More information on NCBI Entrez API keys can be found at New API Keys for the E-utilities. This document describes how to obtain a key in a few minutes.

IMPORTANT: NCBI is transitioning to 3rd party authentication for login. After June 2022, you will no longer be able to use your NCBI userid and password directly. Instead, you will need to login using through a 3rd party such as Google or eRA Commons. In many cases you can login through your university or institutional account.
See My NCBI Help for complete instructions. (The link "See more 3rd party sign in options" will have login information for most major research institutions worldwide.)

Simply paste your NCBI Entrez key into the box and click on Save.

2. Helper Applications

Rationale: BioLegato uses a variety of helper applications to display output from programs. For example, if output is text, a text editor is called. If the output is PDF, a PDF viewer (eg. Adobe Reader) is called. If output is a web page, a web browser (eg. Firefox) is called.

Because the choice of helper programs varies from system to system and platform to platform, the BIRCH installer checks to see which programs are actually on your system when BIRCH is installed, and chooses a default viewer for each type of file.

In the BIRCH, choose Edit --> BLHelper

Note that for each type of file, there is a pull-down menu from which you can choose from a variety of programs for a given task. Of the possible choices, only those actually on your system will appear in the menu. The Test button tries to run the program using a sample file. When you are satisfied, with a choice, click on Save to apply your change.

Example: Changing the default PDF viewer

On Linux systems, the default PDF viewer is Evince. To change that choice to Adobe Reader, choose Adobe Reader.

Make sure to test your choice by clicking on the Test button. If a sample PDF file appears on the screen, then your new choice works.

Finally, Click on Save to save your change.

Example: Using custom commands

For each of the major platforms (eg. Mac OSX, Linux), BLHelper has a list of programs known to be available for that platform. However, if a program is not seen in the menu, you can still launch it using a Custom Command. For example, on Mac OSX, to tell BioLegato to use the Opera web browser, to to the Web Browser line and set 'Custom command'. Type the command to execute Opera in the white box.
Make sure to Test your command, and then Save it to apply the change.

This example illustrates a point specific for MacOSX. On OSX, most desktop applications are packaged as Apps. For example, Opera would be found in a folder called /Applications/Opera.app. Apps are run using the open command with the -a option. Thus, the command to run Opera.app is 'open -a Opera'.

Please send suggestions of comments regarding this page to psgendb@cc.umanitoba.ca