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)
Database Managed Settings
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).
Isabl API Settings
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 methodsas three-value tuples (value, verbose name, system_id modifier). For example:[("SINGLE-CELL RNA", "SINGLE-CELL RNA", "scRNA")]
API_V1_EXTRA_PATTERNS
Import String
Import path to a list of urlpatternsto append to API v1.
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
Support loading analyses results from a AWS s3 based "BASE_STORAGE_DIRECTORY".  Learn more here.
Learn more about production deployment:
Production Deployment
Loading results from a AWS S3 bucket
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/",
        ...
    }
}
Integrating with Jira
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",
    }
},
Isabl CLI Settings
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"]
Writing Applications
Isabl Web Settings
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
If it's enabled, more information about the onco tree disease is added in the Sample details.
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
See defaults​
Colors to customize the light theme.
darkTheme
Object
See defaults​
Colors to customize the dark theme.
modelIcons
Object
{}
​Material Icon names to customize panel icons.
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",
  }
Example of a custom UI configuration
<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>

Operational Automations

Production Deployment

Last modified 1yr ago

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	Import path to a list of `urlpatterns`to append to API v1.
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	Support loading analyses results from a AWS s3 based "BASE_STORAGE_DIRECTORY". Learn more here.

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"]`

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`	If it's enabled, more information about the onco tree disease is added in the Sample details.
`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`	See defaults	Colors to customize the light theme.
`darkTheme`	`Object`	See defaults	Colors to customize the dark theme.
`modelIcons`	`Object`	`{}`	Material Icon names to customize panel icons.
`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", }