Blacktie Auto-Generated Code Documentation

Todo

DONE Convert docstring style from (given,does,returns) to (:param a: format)

calls.py

Code defining classes to represent and excute pipeline program calls.

class blacktie.utils.calls.BaseCall(yargs, email_info, run_id, run_logs, conditions, mode='analyze')

Defines common methods for all program call types.

__init__(yargs, email_info, run_id, run_logs, conditions, mode='analyze')

initializes a BaseCall object

Parameters:

• yargs – argument tree generated by parsing the yaml config file
• email_info – Bunch() object containing keys: email_from, email_to, email_li
• run_id – id for the whole set of calls
• run_logs – the directory where log file should be put
• conditions – one or a list of condition-dictionaries from yargs.condition_queue
• mode – choices = [‘analyze’,’dry_run’,’qsub_script’]

Returns:

an initialized BaseCall object

_flag_out_dir()

renames out directory, prepending ‘FAILED’ flag: equivalent of mv tophat_Aa0 FAILED.tophat_Aa0

build_out_dir_path()

builds correct out_dir path based on state of self

Returns:out_dir

build_qsub()

Builds and writes this CallObject’s qsub script to current working directory using options provided under the “qsub_options” sub-tree in the yaml config file.

construct_options_list()

converts opt_dict into list encoding proper options to send to the current program: saves to self.

execute()

calls correct program, records results, and manages errors

get_condition_id(condition_dict)

Constructs condition ID :param condition_dict: a dictionary containing consition info like name, replicate_id, etc. :returns: an ID used to construct the call_id of a call.

init_log_file()

creates empty log file for this call and stores its path in self.log_file

init_opt_dict()

builds a dict with non-job-specific values set and job-specific values set to False based on option names in the yaml file for this phase

Returns:partially populated opt_dict

log_end()

records command string used, program output, and the end of call in self.log_file

log_msg(log_msg='')

• opens self.log_file
• writes log_msg
• closes self.log_file

log_start()

records start of call in self.log_file

notify_end_of_call()

sends notification email informing user that self.call_id has exited

notify_start_of_call()

sends notification email informing user that self.call_id has been initiated

purge_progress_bars(stderr_str)

removes the dynamic progress bars included in some output in case user did not turn them off

set_call_id()

builds and stores this call’s call ID in self.call_id

class blacktie.utils.calls.CuffdiffCall(yargs, email_info, run_id, run_logs, conditions, mode)

Manage a single call to cuffdiff and store associated run data.

__init__(yargs, email_info, run_id, run_logs, conditions, mode)

initializes the CuffdiffCall object

Parameters:

• yargs – argument tree generated by parsing the yaml config file
• email_info – Bunch() object containing keys: email_from, email_to, email_li
• run_id – id for the whole set of calls
• run_logs – the directory where log file should be put
• conditions – one or a list of condition-dictionaries from yargs.condition_queue
• mode – choices = [‘analyze’,’dry_run’,’qsub_script’]

Returns:

an initialized CuffdiffCall object

get_bam_path(condition)

Supports self.get_sample_bams().

get_cuffmerge_gtf()

Handles yaml_config.cuffdiff_options.positional_args.transcripts_gtf: from_conditions.

get_genome()

Handles yaml_config.cuffdiff_options.frag-bias-correct: from_conditions.

get_labels()

Handles yaml_config.cuffdiff_options.labels: from_conditions.

get_mask_file()

Handles yaml_config.cuffdiff_options.mask-file: from_conditions.

get_out_dir()

Handles yaml_config.cuffdiff_options.o: from_conditions.

get_sample_bams()

Handles yaml_config.cuffdiff_options.positional_args.sample_bams: from_conditions.

class blacktie.utils.calls.CufflinksCall(yargs, email_info, run_id, run_logs, conditions, mode)

Manage a single call to cufflinks and store associated run data.

__init__(yargs, email_info, run_id, run_logs, conditions, mode)

initializes the CufflinksCall object

Parameters:

• yargs – argument tree generated by parsing the yaml config file
• email_info – Bunch() object containing keys: email_from, email_to, email_li
• run_id – id for the whole set of calls
• run_logs – the directory where log file should be put
• conditions – one or a list of condition-dictionaries from yargs.condition_queue
• mode – choices = [‘analyze’,’dry_run’,’qsub_script’]

Returns:

an initialized CufflinksCall object

Todo

DONE add support for –GTF in addition to currently supported –GTF-guide

get_accepted_hits()

Handles yaml_config.cufflinks_options.positional_args.accepted_hits: from_conditions.

get_bam_path()

Supports self.get_accepted_hits().

get_genome()

Handles yaml_config.cufflinks_options.frag-bias-correct: from_conditions.

get_gtf_anno()

Handles yaml_config.cufflinks_options.GTF: from_conditions.

get_gtf_anno_guide()

Handles yaml_config.cufflinks_options.GTF-guide: from_conditions.

get_mask_file()

Handles yaml_config.cufflinks_options.mask-file: from_conditions.

get_out_dir()

Handles yaml_config.cufflinks_options.o: from_conditions.

verify_options()

Makes sure that conflicting options were not imported from yaml config file.

Todo

DONE GTF and GTF-guide should not be used together but both can be ommited

class blacktie.utils.calls.CuffmergeCall(yargs, email_info, run_id, run_logs, conditions, mode)

Manage a single call to cuffmerge and store associated run data.

__init__(yargs, email_info, run_id, run_logs, conditions, mode)

initializes the CuffmergeCall object

Parameters:

• yargs – argument tree generated by parsing the yaml config file
• email_info – Bunch() object containing keys: email_from, email_to, email_li
• run_id – id for the whole set of calls
• run_logs – the directory where log file should be put
• conditions – one or a list of condition-dictionaries from yargs.condition_queue
• mode – choices = [‘analyze’,’dry_run’,’qsub_script’]

Returns:

an initialized CuffmergeCall object

get_cuffGTF_path(condition)

Supports self.get_cufflinks_gtfs().

get_cufflinks_gtfs()

Handles yaml_config.cuffmerge_options.positional_args.assembly_list: from_conditions.

get_genome()

Handles yaml_config.cuffmerge_options.ref-sequence: from_conditions.

get_gtf_anno()

Handles yaml_config.cuffmerge_options.ref-gtf: from_conditions.

get_out_dir()

Handles yaml_config.cuffmerge_options.o: from_conditions.

class blacktie.utils.calls.CummerbundCall(yargs, email_info, run_id, run_logs, conditions, mode)

Manage a single call to blacktie-cummerbund script and store associated run data.

__init__(yargs, email_info, run_id, run_logs, conditions, mode)

initializes the CummerbundCall object

Parameters:

• yargs – argument tree generated by parsing the yaml config file
• email_info – Bunch() object containing keys: email_from, email_to, email_li
• run_id – id for the whole set of calls
• run_logs – the directory where log file should be put
• conditions – one or a list of condition-dictionaries from yargs.condition_queue
• mode – choices = [‘analyze’,’dry_run’,’qsub_script’]

Returns:

an initialized CummerbundCall object

get_cuffdiff_dir()

Handles yaml_config.cummerbund_options.cuffdiff-dir: from_conditions.

get_cuffmerge_gtf()

Handles yaml_config.cummerbund_options.gtf-path: from_conditions.

get_out_dir()

Handles yaml_config.cummerbund_options.out: from_conditions.

class blacktie.utils.calls.TophatCall(yargs, email_info, run_id, run_logs, conditions, mode)

Manage a single call to tophat and store associated run data.

__init__(yargs, email_info, run_id, run_logs, conditions, mode)

initializes the TophatCall object

Parameters:

• yargs – argument tree generated by parsing the yaml config file
• email_info – Bunch() object containing keys: email_from, email_to, email_li
• run_id – id for the whole set of calls
• run_logs – the directory where log file should be put
• conditions – one or a list of condition-dictionaries from yargs.condition_queue
• mode – choices = [‘analyze’,’dry_run’,’qsub_script’]

Returns:

an initialized TophatCall object

get_bt_idx()

Handles yaml_config.tophat_options.positional_args.bowtie2_index: from_conditions.

get_gtf_anno()

Handles yaml_config.tophat_options.G: from_conditions.

get_lt_reads()

Handles yaml_config.tophat_options.positional_args.left_reads: from_conditions.

get_out_dir()

Handles yaml_config.tophat_options.o: from_conditions.

get_rt_reads()

Handles yaml_config.tophat_options.positional_args.right_reads: from_conditions.

errors.py

Code defining custom base error classes to provide a foundation for graceful error handling.

exception blacktie.utils.errors.BlacktieError

Base class for exceptions in the blacktie package.

exception blacktie.utils.errors.InvalidFileFormatError

When errors occur due to malformed file formats.

exception blacktie.utils.errors.MissingArgumentError(errMsg)

When a required argument is missing from the parsed command line options.

__init__(errMsg)

exception blacktie.utils.errors.SanityCheckError

When a ‘state check’ comes back as conflicting or nonsensical.

exception blacktie.utils.errors.SystemCallError(errno, strerror, filename=None)

Error raised when a problem occurs while attempting to run an external system call.

Attributes:

errno – return code from system call

filename – file in volved if any

strerror – error msg

__init__(errno, strerror, filename=None)

exception blacktie.utils.errors.UnexpectedValueError

When values that “should” not be possible happen; like if a variable was changed unexpectedly.

externals.py

Code facilitating the execution of external system calls.

blacktie.utils.externals.mkdirp(path)

Create new dir while creating any parent dirs in the path as needed.

blacktie.utils.externals.runExternalApp(progName, argStr)

Convenience func to handle calling and monitoring output of external programs.

Parameters:

• progName – name of system program command
• argStr – string containing command line options for progName

Returns:

subprocess.communicate object

blacktie.utils.externals.whereis(program)

returns path of program if it exists in your $PATH variable or None otherwise

misc.py

Code facilitating random aspects of this package.

class blacktie.utils.misc.Bunch(*args, **kwds)

A dict like class to facilitate setting and access to tree-like data. Allows access to dictionary keys through ‘dot’ notation: “yourDict.key = value”.

__init__(*args, **kwds)

blacktie.utils.misc.bunchify(dict_tree)

Traverses a dictionary tree and converts all sub-dictionaries to Bunch() objects.

blacktie.utils.misc.email_notification(sender, to, subject, txt, pw, server_info)

Sends email to recipient using GMAIL server by default but will now accept server_info to customize this.

Parameters:

• sender – email address of sender
• to – email addres of recipient
• subject – subject text
• txt – body text
• pw – password of sender
• server_info – dictionary = {‘host’:str,’port’:int}

Returns:

None

Todo

DONE make email_notification() adjustable for other email servers

blacktie.utils.misc.get_time()

Return system time formatted as ‘YYYY:MM:DD-hh:mm:ss’.

blacktie.utils.misc.get_version_number(path_to_setup)

Provides access to current version info contained in setup.py

blacktie.utils.misc.map_condition_groups(yargs)

creates a Bunch obj groups with key=’experiment_id’ from yargs, value=list(condition_queue objects with ‘experiment_id’)

Parameters:yargs – argument object generated from the yaml config file Returns:groups

blacktie.utils.misc.whoami()

Returns the name of the currently active function.