Comment on page
Isabl Settings
Each component of Isabl can be configured in multiple ways. Generally, settings are strings, numbers, objects, and many other types.
Import Strings
point to an importable object, whether its a class, a function, etc. (e.g.isabl_cli.data.DataImporter
)Some Isabl API, Isabl Web, and Isabl CLI and be configured from the admin site! To do so, go to
/admin/isabl_api/client/
and update the clients called default-backend-settings
for Isabl API, and default-frontend-settings
for Isabl Web. You may want to create your own client for Isabl CLI (see Writing Applications).Here is a detailed list of available configurations for Isabl API. To configure Isabl API, add a dictionary called
ISABL_SETTINGS
to your Django configuration. Setting Name | Type | Description |
EXTRA_GENDERS | List | Individual genders as two-value tuples (value, verbose name). |
EXTRA_STATUS | List | Analysis status as two-value tuples (value, verbose name). |
EXTRA_RAW_DATA_FORMATS | List | Experiment raw_data formats as two-value tuples (value, verbose name). Learn how to support extra formats here. |
EXTRA_SPECIES | List | Individual species as three-value tuples (value, verbose name, system_id modifier). For example: [("YEAST", "YEAST", "Y")] |
EXTRA_SAMPLE_CATEGORIES | List | Sample categories as three-value tuples (value, verbose name, system_id modifier). For example[("UNKNOWN", "UNKNOWN", "U")] |
EXTRA_TECHNIQUE_METHODS | List | Technique methods as three-value tuples (value, verbose name, system_id modifier). For example:[("SINGLE-CELL RNA", "SINGLE-CELL RNA", "scRNA")] |
API_V1_EXTRA_PATTERNS | Import String | |
SYSTEM_ID_PREFIX | String | A prefix for the default sample ID generated by Isabl (with the hope to differentiate objects across Isabl instances). For example, if set to DEMO , then experiments might be named DEMO_H000002_T01_01_TD01 . |
SYSTEM_ID_GENERATOR | Import String | Import path to a function that takes either an Individual , Sample , Aliquot , or Experiment and returns a system identifier. This will overwrite the default generation of system ids (e.g. DEMO_H000002_T01_01_TD01 ). |
FRONTEND_URL | String | URL where the frontend is being deployed (not required if frontend running in same host as backend). |
JIRA_SETTINGS | Dictionary | Feature to integrate JIRA with Isabl projects (It can assign a different JIRA epic to each Isabl Group). See more. |
REQUIRE_ACCOUNT_APPROVAL | Boolean | Disable new accounts and send out email to admins to require approval before new users can login. |
S3_BASE_STORAGE_DIRECTORIES | Dictionary |
Learn more about production deployment:
If your Isabl CLI
BASE_STORAGE_DIRECTORY
is located in a S3 bucket, you can enable rendering results through the website using the S3_BASE_STORAGE_DIRECTORIES
setting:"S3_BASE_STORAGE_DIRECTORIES": {
"/base/path/in/output-file": {
"bucket": "an-S3-bucket-name",
"access_key": "The AWS Access Key",
"access_key": "The AWS Access Key",
"base_directory": "/base/path/in/s3/object",
}
}
For example if an analysis output path is
/mnt/data/analyses/01/01/1/head_job.log
and and the s3 path to it is s3://my-bucket/data/analyses/01/01/1/head_job.log
you should use this setting:"S3_BASE_STORAGE_DIRECTORIES": {
"/mnt/data/": {
"bucket": "my-bucket",
"base_directory": "/data/",
...
}
}
Isabl provides a simple integration to Jira, as it's a widely used management tool used for development and analyses. The module creates a Jira Epic for each Isabl project, and allows to create a simple list of tasks (Jira issues) from the web.

Jira Integration Demo
To enable, you need to add the following settings in the web and in the api.
In the Web Settings:
index.html
window.$isabl = {
...
jira: true
}
In the Api Settings:
In Jira for Epic and Issues we can create custom fields. You need to create 2 custom fields where the Project ID and the Project Link will be stored, and use their ids in the settings.
"JIRA_SETTINGS": {
"active": True,
"default": {
"URL": "https://my-jira-instance",
"AUTH": ("jira-username", "secret-jira-password"),
"PROJECT_KEY": "ISABL",
"URL_FIELD": "customfield_id_1",
"PROJECT_FIELD": "customfield_id_2",
}
},
Pro Tip: Jira Epics are created under Jira Projects. You can create different Jira Projects for each Isabl Project Group, by adding extra dictionaries that map to isabl group acronyms.
i.e. If a group in Isabl is called (name: Pathology, acronym: PATH), you can set up your settings like the example below. And all Isabl Projects that belong to the PATHOLOGY group, will have their own separate Jira Project under
https://my-jira-instance/projects/PATH/issues/
"JIRA_SETTINGS": {
"active": True,
"default": {
"URL": "https://my-jira-instance",
"AUTH": ("jira-username", "secret-jira-password"),
"PROJECT_KEY": "ISABL",
"URL_FIELD": "customfield_id_1",
"PROJECT_FIELD": "customfield_id_2",
},
"PATH": {
"URL": "https://my-jira-instance",
"AUTH": ("jira-username", "secret-jira-password"),
"PROJECT_KEY": "PATH",
"URL_FIELD": "customfield_id_1",
"PROJECT_FIELD": "customfield_id_2",
}
},
Before anything, you must set the following environment variables:
# you need to let Isabl CLI where the API is being hosted
export ISABL_API_URL='your-isabl-instance.org/api/v1/'
# you can create a client object in from the django admin
export ISABL_CLIENT_ID=<insert-client-primary-key-or-slug>
Once this is set, you can configure your client object settings with the following configurations (see
isabl_cli.settings
to check default settings):Setting Name | Type | Description |
API_BASE_URL | String | url host where your isabl api is running. Needed to connect the CLI with the API. |
BASE_STORAGE_DIRECTORY | String | Directory where data will be store in the file system. |
TIME_ZONE | String | Current timezone used by pytz package. |
INSTALLED_APPLICATIONS | Import Strings Array | Array of registered applications to be run with the cli tool. These apps can be seen and run isabl apps --help . |
CUSTOM_COMMANDS | Import Strings Array | Array of custom commands to be added to the custom cli tool. |
SYSTEM_COMMANDS | Import Strings Array | Array of system commands that are used in isabl-cli. |
ADMIN_COMMANDS | Import Strings Array | Array of commands that are only executable by admin. |
ADMIN_USER | String | Linux user for which admin operations will be limited. This user will own the data and analyses results. Nevertheless, Isabl Applications can be run by multiple unix users. Learn more about it here. |
CREATE_SYMLINKS | Boolean | By default, Isabl creates a symlink farm upon data import and analyses completion. You can turn it off with this setting. |
DEFAULT_LINUX_GROUP | String | Linux group for data admin_user to use. |
MAKE_STORAGE_DIRECTORY | Import String | Get and create path to a data directory. |
TRASH_ANALYSIS_STORAGE | Import String | Move analysis storage_url to a trash directory. |
REFERENCE_DATA_IMPORTER | Import String | Register input_bed_path in technique's storage dir and update data. |
DATA_IMPORTER | Import String | Import raw data for multiple experiments. |
BED_IMPORTER | Import String | Register input_bed_path in technique's storage dir and update data. |
ON_DATA_IMPORT | Import Strings Array | Methods triggered when data has been imported successfully. |
ON_STATUS_CHANGE | Import Strings Array | Methods triggered when an analysis changes status. |
ON_SIGNAL_FAILURE | Import Strings Array | Methods triggered when an signal fails. |
SUBMIT_ANALYSES | Import String | A function that will take a list tuples (analysis, path to analysis script) and submits them to a given compute architecture. |
SUBMIT_CONFIGURATION | Dictionary | A schema-less dictionary to set configurations that the SUBMIT_ANALYSES function may utilize. |
EXTRA_RAW_DATA_FORMATS | Tuples Array | For every new supported format a tuple of (regex validator, file_data_type) i.e. To support Illumina ORA format: ["\\.ora?$", "ORA"] |
Customization of the User Interface can be achieved by defining a global
$isabl
settings dictionary in the main index.html
.<script>
window.$isabl = { }
</script>
You can configure the
window.$isabl
with the following parameters:Setting Name | Type | Default | Description |
apiHost | String | '' | Url host where your isabl api is running. |
name | String | 'isabl' | Custom app title that is shown in the top of the app. |
logo | String | | Custom image path that is shown as the main logo of the app. Use a square size image for better display. |
jira | Boolean | false | Activate the jira card in the projects view. If the jira endpoint is available from the api, it will show the current tickets for each project. Learn more about jira integration. |
oncoTree | Boolean | false | |
customFields | Object | {} | Every detail info for each model shown in the frontend can be customized, by overwriting the specific key of a fields object. Available fields can be seen here. Learn more on how to create custom fields (TODO). |
restartButton | Boolean | false | If enabled, FAILED analyses can send a signal to restart or force to the database. Learn more in signals (TODO). |
lightTheme | Object | Colors to customize the light theme. | |
darkTheme | Object | Colors to customize the dark theme. | |
modelIcons | Object | {} | |
distinctRecords | Boolean | false | By default, api queries don't remove duplicates as it impacts speed. Set true to avoid duplicate records. |
treeIcons | Object | {} | Please use these if the graph icons are broken: "treeIcons": { "male": "https://isabl-web.s3.us-east-1.amazonaws.com/male.svg", "female": "https://isabl-web.s3.us-east-1.amazonaws.com/female.svg", "normal": "https://isabl-web.s3.us-east-1.amazonaws.com/normal.svg", "tumor": "https://isabl-web.s3.us-east-1.amazonaws.com/tumor.png", "aliquot": "https://isabl-web.s3.us-east-1.amazonaws.com/normal.svg", "dna": "https://isabl-web.s3.us-east-1.amazonaws.com/dna.svg", "rna": "https://isabl-web.s3.us-east-1.amazonaws.com/rna.svg", "mouse": "https://isabl-web.s3.us-east-1.amazonaws.com/mouse.svg", "image": "https://isabl-web.s3.us-east-1.amazonaws.com/image.svg", "alien": "https://isabl-web.s3.us-east-1.amazonaws.com/unknown.svg", } |
<script>
const customFields = {
// overwrite 2 of the fields of the analysis panel
analysisFields: {
// Add a new formatter for status
status: {
section: 'Analysis Details',
verboseName: 'Status',
field: 'status',
formatter: value => {
if (value === 'SUCEEDED') {
return 'DONE!'
} else if (value === 'FAILED') {
return 'OOPS...'
} else {
return value
}
}
},
// Make notes not editable
notes: {
section: 'Analysis Details',
verboseName: 'Notes',
field: 'notes',
editable: false
}
},
// display a new custom field for project that exist in the db.
// Use http://<api-host>/admin/ to create custom fields.
projectFields: {
// custom field
irbConstent: {
section: 'Project Details',
verboseName: 'IRB Consent',
field: 'custom_fields.irb_consent',
editable: true,
apiPermission: 'change_project'
}
}
}
}
window.$isabl = {
apiHost: "http://my.isabl.api.host",
name: "My Cool App",
logo: "/path/to/my/awesome/logo",
customFields,
restartButton: true,
jira: true,
oncoTree: true,
darkTheme: {
primary: '#1dc5a7',
background: '#1a202c',
surface: '#3a4556',
accent: '#4a5568'
},
modelIcons: {
project: 'insert_chart',
analysis: 'bubble_chart',
individual: 'person',
sample: 'gesture',
experiment: 'flash_on',
search: 'search',
submission: 'assignment'
},
}
</script>
Important: In case you're running your frontend instance in a different host that the backend, you should add this
ENV
variable to your django project where the isabl-api
is running:export FRONTEND_URL="http://your-frontend-host.com"
If you want to consume
isabl-web
and serve your own html, outside of isabl-api
. You can consume the frontend just as:index.html
<!DOCTYPE html>
<html>
<head>
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<meta name="viewport" content="width=device-width,initial-scale=1">
<meta charset="UTF-8">
<link href='https://fonts.googleapis.com/css?family=Roboto:300,400,500,700|Material+Icons' rel="stylesheet" type="text/css">
<link rel="icon" href="favicon.ico">
<title>My Awesome App</title>
</head>
<body>
<div id="isabl-web"></div>
<script src="https://cdn.jsdelivr.net/npm/vue"></script>
<script src="https://cdn.jsdelivr.net/npm/isabl-web"></script>
<script>
window.$isabl = {
apiHost: "http://my.isabl.api.host",
//... other settings
}
</script>
</body>
</html>
Last modified 1yr ago