Instruction:
Given the following Python 3 function, write the documentation
def _init_exons(self):
        exon_starts = [self.chrom_start + int(s)
                       for s in self.bed_tuple.blockStarts.strip(',').split(',')]
        exon_sizes = list(map(int, self.bed_tuple.blockSizes.strip(',').split(',')))

        # get chromosome intervals
        exons = [(exon_starts[i], exon_starts[i] + exon_sizes[i])
                 for i in range(len(exon_starts))]
        no_utr_exons = self._filter_utr(exons)
        self.exons = no_utr_exons
        self.exon_lens = [e[1] - e[0] for e in self.exons]
        self.num_exons = len(self.exons)
        self.cds_len = sum(self.exon_lens)
        self.five_ss_len = 2*(self.num_exons-1)
        self.three_ss_len = 2*(self.num_exons-1)
        self._init_splice_site_pos()

Response: Sets a list of position intervals for each exon.


Instruction:
Explain what the following Python 3 code does
def init_genome_coordinates(self) :
        self.seqpos2genome = {}

        # record genome positions for each sequence position
        seq_pos = 0
        for estart, eend in self.exons:
            for genome_pos in range(estart, eend):
                if self.strand == '+':
                    self.seqpos2genome[seq_pos] = genome_pos
                elif self.strand == '-':
                    tmp = self.cds_len - seq_pos - 1
                    self.seqpos2genome[tmp] = genome_pos
                seq_pos += 1

        # recode 5' splice site locations
        for i in range(0, self.five_ss_len):
            seq_pos = self.cds_len + i
            ss_ix = i // 2  # the ss_ix'th 5'ss starting from upstream tx
            pos_in_ss = i % 2  # whether first/second nuc in splice site

            # determine genome coordinates for 5' splice site
            if self.strand == '+':
                self.seqpos2genome[seq_pos] = self.exons[ss_ix][1] + pos_in_ss
            else:
                exon_pos = -1 - ss_ix
                self.seqpos2genome[seq_pos] = self.exons[exon_pos][0] - pos_in_ss - 1

        # recode 3' splice site locations
        for i in range(0, self.three_ss_len):
            seq_pos = self.cds_len + self.five_ss_len + i
            ss_ix = i // 2  # the ss_ix'th 3'ss starting from upstream tx
            pos_in_ss = i % 2  # whether first/second nuc in splice site

            # determine genome coordinates for 3' splice site
            if self.strand == '+':
                self.seqpos2genome[seq_pos] = self.exons[ss_ix+1][0] - 2 + pos_in_ss
            else:
                exon_pos = -1 - ss_ix
                self.seqpos2genome[seq_pos] = self.exons[exon_pos-1][1] + 1 - pos_in_ss

Response: Creates the self. seqpos2genome dictionary that converts positions relative to the sequence to genome coordinates.


Instruction:
Write a Python 3 script to
return the relative position on the coding sequence for a given genomic position.

Response:
def query_position(self, strand, chr, genome_coord):
        """Provides the relative position on the coding sequence for a given
        genomic position.

        Parameters
        ----------
        chr : str
            chromosome, provided to check validity of query
        genome_coord : int
            0-based position for mutation, actually used to get relative coding pos

        Returns
        -------
        pos : int or None
            position of mutation in coding sequence, returns None if mutation
            does not match region found in self.exons
        """
        # first check if valid
        pos = None  # initialize to invalid pos
        if chr != self.chrom:
            #logger.debug('Wrong chromosome queried. You provided {0} but gene is '
                         #'on {1}.'.format(chr, self.chrom))
            # return pos
            pass

        if type(genome_coord) is list:
            # handle case for indels
            pos_left = self.query_position(strand, chr, genome_coord[0])
            pos_right = self.query_position(strand, chr, genome_coord[1])
            if pos_left is not None or pos_right is not None:
                return [pos_left, pos_right]
            else:
                return None

        # return position if contained within coding region or splice site
        for i, (estart, eend) in enumerate(self.exons):
            # in coding region
            if estart <= genome_coord < eend:
                if strand == '+':
                    prev_lens = sum(self.exon_lens[:i])  # previous exon lengths
                    pos = prev_lens + (genome_coord - estart)
                elif strand == '-':
                    prev_lens = sum(self.exon_lens[:i])  # previous exon lengths
                    pos = prev_lens + (genome_coord - estart)
                    pos = self.cds_len - pos - 1  # flip coords because neg strand
                return pos
            # in splice site
            elif (eend <= genome_coord < eend + 2) and i != self.num_exons-1:
                if strand == '+':
                    pos = self.cds_len + 2*i + (genome_coord - eend)
                elif strand == '-':
                    pos = self.cds_len + self.five_ss_len + 2*(self.num_exons-(i+2)) + (genome_coord - eend)
                return pos
            # in splice site
            elif (estart - 2 <= genome_coord < estart) and i != 0:
                if strand == '-':
                    pos = self.cds_len + 2*(self.num_exons-(i+2)) + (genome_coord - (estart - 2))
                elif strand == '+':
                    pos = self.cds_len + self.five_ss_len + 2*(i-1) + (genome_coord - (estart - 2))
                return pos

        return pos


Instruction:
Here you have a function in Python 3, explain what it does
def start_logging(log_file='', log_level='INFO', verbose=False):
    if not log_file:
        # create log directory if it doesn't exist
        log_dir = os.path.abspath('log') + '/'
        if not os.path.isdir(log_dir):
            os.mkdir(log_dir)

        # path to new log file
        log_file = log_dir + 'log.run.' + str(datetime.datetime.now()).replace(':', '.') + '.txt'

    # logger options
    lvl = logging.DEBUG if log_level.upper() == 'DEBUG' else logging.INFO

    # ignore warnings if not in debug
    if log_level.upper() != 'DEBUG':
        warnings.filterwarnings('ignore')

    # define logging format
    if verbose:
        myformat = '%(asctime)s - %(name)s - %(levelname)s \n>>>  %(message)s'
    else:
        myformat = '%(message)s'

    # create logger
    if not log_file == 'stdout':
        # normal logging to a regular file
        logging.basicConfig(level=lvl,
                            format=myformat,
                            filename=log_file,
                            filemode='w')
    else:
        # logging to stdout
        root = logging.getLogger()
        root.setLevel(lvl)
        stdout_stream = logging.StreamHandler(sys.stdout)
        stdout_stream.setLevel(lvl)
        formatter = logging.Formatter(myformat)
        stdout_stream.setFormatter(formatter)
        root.addHandler(stdout_stream)
        root.propagate = True

Response: Start logging information into the log directory.


Instruction:
Write a Python 3 function for
writing exception to log file if occured in decorated function. This decorator wrapper is needed for multiprocess logging since otherwise the python multiprocessing module will obscure the actual line of the error.

Response:
def log_error_decorator(f):
    """Writes exception to log file if occured in decorated function.

    This decorator wrapper is needed for multiprocess logging since otherwise
    the python multiprocessing module will obscure the actual line of the error.
    """
    @wraps(f)
    def wrapper(*args, **kwds):
        try:
            result = f(*args, **kwds)
            return result
        except KeyboardInterrupt:
            logger.info('Ctrl-C stopped a process.')
        except Exception as e:
            logger.exception(e)
            raise
    return wrapper


Instruction:
Given the following Python 3 function, write the documentation
def filter_list(mylist, bad_ixs):
    # indices need to be in reverse order for filtering
    # to prevent .pop() from yielding eroneous results
    bad_ixs = sorted(bad_ixs, reverse=True)
    for i in bad_ixs:
        mylist.pop(i)
    return mylist

Response: Removes indices from a list.


Instruction:
Can you create a Python 3 function that
gets reverse complement of sequence.

Response:
def rev_comp(seq):
    """Get reverse complement of sequence.

    rev_comp will maintain the case of the sequence.

    Parameters
    ----------
    seq : str
        nucleotide sequence. valid {a, c, t, g, n}

    Returns
    -------
    rev_comp_seq : str
        reverse complement of sequence
    """
    rev_seq = seq[::-1]
    rev_comp_seq = ''.join([base_pairing[s] for s in rev_seq])
    return rev_comp_seq


Instruction:
Can you implement a function in Python 3 that
iterates through a BED file yielding parsed BED lines.

Response:
def bed_generator(bed_path):
    """Iterates through a BED file yielding parsed BED lines.

    Parameters
    ----------
    bed_path : str
        path to BED file

    Yields
    ------
    BedLine(line) : BedLine
        A BedLine object which has parsed the individual line in
        a BED file.
    """
    with open(bed_path) as handle:
        bed_reader = csv.reader(handle, delimiter='\t')
        for line in bed_reader:
            yield BedLine(line)


Instruction:
Write a Python 3 function that can
read a BED file and populates a dictionary separating genes by chromosome.

Response:
def read_bed(file_path, restricted_genes=None):
    """Reads BED file and populates a dictionary separating genes
    by chromosome.

    Parameters
    ----------
    file_path : str
        path to BED file
    filtered_genes: list
        list of gene names to not use

    Returns
    -------
    bed_dict: dict
        dictionary mapping chromosome keys to a list of BED lines
    """
    # read in entire bed file into a dict with keys as chromsomes
    bed_dict = OrderedDict()
    for bed_row in bed_generator(file_path):
        is_restrict_flag = restricted_genes is None or bed_row.gene_name in restricted_genes
        if is_restrict_flag:
            bed_dict.setdefault(bed_row.chrom, [])
            bed_dict[bed_row.chrom].append(bed_row)
    sort_chroms = sorted(bed_dict.keys(), key=lambda x: len(bed_dict[x]), reverse=True)
    bed_dict = OrderedDict((chrom, bed_dict[chrom]) for chrom in sort_chroms)
    return bed_dict


Instruction:
Create a Python 3 function to
remove invalid and correct mutations for 1 - based coordinates.

Response:
def _fix_mutation_df(mutation_df, only_unique=False):
    """Drops invalid mutations and corrects for 1-based coordinates.

    TODO: Be smarter about what coordinate system is put in the provided
    mutations.

    Parameters
    ----------
    mutation_df : pd.DataFrame
        user provided mutations
    only_unique : bool
        flag indicating whether only unique mutations for each tumor sample
        should be kept. This avoids issues when the same mutation has
        duplicate reportings.

    Returns
    -------
    mutation_df : pd.DataFrame
        mutations filtered for being valid and correct mutation type. Also
        converted 1-base coordinates to 0-based.

    """
    # only keep allowed mutation types
    orig_len = len(mutation_df)  # number of mutations before filtering
    mutation_df = mutation_df[mutation_df.Variant_Classification.isin(variant_snv)]  # only keep SNV
    type_len = len(mutation_df)  # number of mutations after filtering based on mut type

    # log the number of dropped mutations
    log_msg = ('Dropped {num_dropped} mutations after only keeping '
               '{mut_types}. Indels are processed separately.'.format(num_dropped=orig_len-type_len,
                                                                      mut_types=', '.join(variant_snv)))
    logger.info(log_msg)

    # check if mutations are valid SNVs
    valid_nuc_flag = (mutation_df['Reference_Allele'].apply(is_valid_nuc) & \
                      mutation_df['Tumor_Allele'].apply(is_valid_nuc))
    mutation_df = mutation_df[valid_nuc_flag]  # filter bad lines
    mutation_df = mutation_df[mutation_df['Tumor_Allele'].apply(lambda x: len(x)==1)]
    mutation_df = mutation_df[mutation_df['Reference_Allele'].apply(lambda x: len(x)==1)]
    valid_len = len(mutation_df)

    # log the number of dropped mutations
    log_msg = ('Dropped {num_dropped} mutations after only keeping '
               'valid SNVs'.format(num_dropped=type_len-valid_len))
    logger.info(log_msg)

    # drop duplicate mutations
    if only_unique:
        dup_cols = ['Tumor_Sample', 'Chromosome', 'Start_Position',
                    'End_Position', 'Reference_Allele', 'Tumor_Allele']
        mutation_df = mutation_df.drop_duplicates(subset=dup_cols)

        # log results of de-duplication
        dedup_len = len(mutation_df)
        log_msg = ('Dropped {num_dropped} mutations when removing '
                   'duplicates'.format(num_dropped=valid_len-dedup_len))
        logger.info(log_msg)

    # add dummy Protein_Change or Tumor_Type columns if not provided
    # in file
    if 'Tumor_Type' not in mutation_df.columns:
        mutation_df['Tumor_Type'] = ''
    if 'Protein_Change' not in mutation_df.columns:
        mutation_df['Protein_Change'] = ''

    # correct for 1-based coordinates
    mutation_df['Start_Position'] = mutation_df['Start_Position'].astype(int) - 1
    return mutation_df


Instruction:
Can you write a function in Python 3 where it
calculates the sum of mutations within a particular window around a particular mutated amino acid.

Response:
def calc_windowed_sum(aa_mut_pos,
                      germ_aa,
                      somatic_aa,
                      window=[3]):
    """Calculate the sum of mutations within a window around a particular mutated
    codon.

    Parameters
    ----------
    aa_mut_pos : list
        list of mutated amino acid positions
    germ_aa : list
        Reference amino acid
    somatic_aa : list
        Somatic amino acid (if missense)
    window : list
        List of windows to calculate for

    Returns
    -------
    pos_ctr : dict
        dictionary of mutated positions (key) with associated counts (value)
    pos_sum : dict of dict
        Window size as first key points to dictionary of mutated positions (key)
        with associated mutation count within the window size (value)
    """
    pos_ctr, pos_sum = {}, {w: {} for w in window}
    num_pos = len(aa_mut_pos)
    # figure out the missense mutations
    for i in range(num_pos):
        pos = aa_mut_pos[i]
        # make sure mutation is missense
        if germ_aa[i] and somatic_aa[i] and germ_aa[i] != '*' and \
           somatic_aa[i] != '*' and germ_aa[i] != somatic_aa[i]:
            # should have a position, but if not skip it
            if pos is not None:
                pos_ctr.setdefault(pos, 0)
                pos_ctr[pos] += 1

    # calculate windowed sum
    pos_list = sorted(pos_ctr.keys())
    max_window = max(window)
    for ix, pos in enumerate(pos_list):
        tmp_sum = {w: 0 for w in window}
        # go through the same and lower positions
        for k in reversed(range(ix+1)):
            pos2 = pos_list[k]
            if pos2 < pos-max_window: break
            for w in window:
                if pos-w <= pos2:
                    tmp_sum[w] += pos_ctr[pos2]
        # go though the higher positions
        for l in range(ix+1, len(pos_list)):
            pos2 = pos_list[l]
            if pos2 > pos+max_window: break
            for w in window:
                if pos2 <= pos+w:
                    tmp_sum[w] += pos_ctr[pos2]
        # iterate through all other positions
        #for pos2 in pos_list:
            #for w in window:
                #if pos-w <= pos2 <= pos+w:
                    #tmp_sum[w] += pos_ctr[pos2]
        # update windowed counts
        for w in window:
            pos_sum[w][pos] = tmp_sum[w]

    return pos_ctr, pos_sum


Instruction:
Make a summary of the following Python 3 code
def get_all_context_names(context_num):
    if context_num == 0:
        return ['None']
    elif context_num == 1:
        return ['A', 'C', 'T', 'G']
    elif context_num == 1.5:
        return ['C*pG', 'CpG*', 'TpC*', 'G*pA',
                'A', 'C', 'T', 'G']
    elif context_num == 2:
        dinucs = list(set(
            [d1+d2
             for d1 in 'ACTG'
             for d2 in 'ACTG']
        ))
        return dinucs
    elif context_num == 3:
        trinucs = list(set(
            [t1+t2+t3
             for t1 in 'ACTG'
             for t2 in 'ACTG'
             for t3 in 'ACTG']
        ))
        return trinucs

Response: Returns a list of all base context names for a given context number.


Instruction:
How would you explain what the following Python 3 function does
def get_chasm_context(tri_nuc):
    # check if string is correct length
    if len(tri_nuc) != 3:
        raise ValueError('Chasm context requires a three nucleotide string '
                         '(Provided: "{0}")'.format(tri_nuc))

    # try dinuc context if found
    if tri_nuc[1:] == 'CG':
        return 'C*pG'
    elif tri_nuc[:2] == 'CG':
        return 'CpG*'
    elif tri_nuc[:2] == 'TC':
        return 'TpC*'
    elif tri_nuc[1:] == 'GA':
        return 'G*pA'
    else:
        # just return single nuc context
        return tri_nuc[1]

Response: Returns the ChASM s mutation context acording to CHASM s NUC string.


Instruction:
Can you write a function in Python 3 where it
retrieves relevant information about the effect of a somatic mutation effect on the amino acid of a gene.

Response:
def get_aa_mut_info(coding_pos, somatic_base, gene_seq):
    """Retrieves relevant information about the effect of a somatic
    SNV on the amino acid of a gene.

    Information includes the germline codon, somatic codon, codon
    position, germline AA, and somatic AA.

    Parameters
    ----------
    coding_pos : iterable of ints
        Contains the base position (0-based) of the mutations
    somatic_base : list of str
        Contains the somatic nucleotide for the mutations
    gene_seq : GeneSequence
        gene sequence

    Returns
    -------
    aa_info : dict
        information about the somatic mutation effect on AA's
    """
    # if no mutations return empty result
    if not somatic_base:
        aa_info = {'Reference Codon': [],
                   'Somatic Codon': [],
                   'Codon Pos': [],
                   'Reference Nuc': [],
                   'Reference AA': [],
                   'Somatic AA': []}
        return aa_info

    # get codon information into three lists
    ref_codon, codon_pos, pos_in_codon, ref_nuc = zip(*[cutils.pos_to_codon(gene_seq, p)
                                                    for p in coding_pos])
    ref_codon, codon_pos, pos_in_codon, ref_nuc = list(ref_codon), list(codon_pos), list(pos_in_codon), list(ref_nuc)

    # construct codons for mutations
    mut_codon = [(list(x) if x != 'Splice_Site' else []) for x in ref_codon]
    for i in range(len(mut_codon)):
        # splice site mutations are not in a codon, so skip such mutations to
        # prevent an error
        if pos_in_codon[i] is not None:
            pc = pos_in_codon[i]
            mut_codon[i][pc] = somatic_base[i]
    mut_codon = [(''.join(x) if x else 'Splice_Site') for x in mut_codon]

    # output resulting info
    aa_info = {'Reference Codon': ref_codon,
               'Somatic Codon': mut_codon,
               'Codon Pos': codon_pos,
               'Reference Nuc': ref_nuc,
               'Reference AA': [(utils.codon_table[r] if (r in utils.codon_table) else None)
                                for r in ref_codon],
               'Somatic AA': [(utils.codon_table[s] if (s in utils.codon_table) else None)
                              for s in mut_codon]}

    return aa_info


Instruction:
Create a Python 3 function for
handling result from TSG process and converts to dataframe.

Response:
def handle_tsg_results(permutation_result):
    """Handles result from TSG results.

    Takes in output from multiprocess_permutation function and converts to
    a better formatted dataframe.

    Parameters
    ----------
    permutation_result : list
        output from multiprocess_permutation

    Returns
    -------
    permutation_df : pd.DataFrame
        formatted output suitable to save
    """
    permutation_df = pd.DataFrame(sorted(permutation_result, key=lambda x: x[2] if x[2] is not None else 1.1),
                                  columns=['gene', 'inactivating count', 'inactivating p-value',
                                           'Total SNV Mutations', 'SNVs Unmapped to Ref Tx'])
    permutation_df['inactivating p-value'] = permutation_df['inactivating p-value'].astype('float')
    tmp_df = permutation_df[permutation_df['inactivating p-value'].notnull()]

    # get benjamani hochberg adjusted p-values
    permutation_df['inactivating BH q-value'] = np.nan
    permutation_df.loc[tmp_df.index, 'inactivating BH q-value'] = mypval.bh_fdr(tmp_df['inactivating p-value'])

    # sort output by p-value. due to no option to specify NaN order in
    # sort, the df needs to sorted descendingly and then flipped
    permutation_df = permutation_df.sort_values(by='inactivating p-value', ascending=False)
    permutation_df = permutation_df.reindex(index=permutation_df.index[::-1])

    # order result
    permutation_df = permutation_df.set_index('gene', drop=False)
    col_order  = ['gene', 'Total SNV Mutations', 'SNVs Unmapped to Ref Tx',
                  #'Total Frameshift Mutations', 'Frameshifts Unmapped to Ref Tx',
                  'inactivating count', 'inactivating p-value',
                  'inactivating BH q-value']
    return permutation_df[col_order]


Instruction:
Can you tell what is the following Python 3 function doing
def handle_oncogene_results(permutation_result, num_permutations):
    mycols = ['gene', 'num recurrent', 'position entropy',
              'mean vest score', 'entropy p-value',
              'vest p-value', 'Total Mutations', 'Unmapped to Ref Tx']
    permutation_df = pd.DataFrame(permutation_result, columns=mycols)

    # get benjamani hochberg adjusted p-values
    permutation_df['entropy BH q-value'] = mypval.bh_fdr(permutation_df['entropy p-value'])
    permutation_df['vest BH q-value'] = mypval.bh_fdr(permutation_df['vest p-value'])

    # combine p-values
    permutation_df['tmp entropy p-value'] = permutation_df['entropy p-value']
    permutation_df['tmp vest p-value'] = permutation_df['vest p-value']
    permutation_df.loc[permutation_df['entropy p-value']==0, 'tmp entropy p-value'] = 1. / num_permutations
    permutation_df.loc[permutation_df['vest p-value']==0, 'tmp vest p-value'] = 1. / num_permutations
    permutation_df['combined p-value'] = permutation_df[['entropy p-value', 'vest p-value']].apply(mypval.fishers_method, axis=1)
    permutation_df['combined BH q-value'] = mypval.bh_fdr(permutation_df['combined p-value'])
    del permutation_df['tmp vest p-value']
    del permutation_df['tmp entropy p-value']

    # order output
    permutation_df = permutation_df.set_index('gene', drop=False)  # make sure genes are indices
    permutation_df['num recurrent'] = permutation_df['num recurrent'].fillna(-1).astype(int)  # fix dtype isssue
    col_order = ['gene', 'Total Mutations', 'Unmapped to Ref Tx',
                 'num recurrent', 'position entropy',
                 'mean vest score', 'entropy p-value',
                 'vest p-value', 'combined p-value', 'entropy BH q-value',
                 'vest BH q-value', 'combined BH q-value']
    permutation_df = permutation_df.sort_values(by=['combined p-value'])
    return permutation_df[col_order]

Response:
Takes in output from multiprocess_permutation function and converts to
    a better formatted dataframe.


Instruction:
Create a Python 3 function to
take in output from multiprocess_permutation function and converts to a better formatted dataframe.

Response:
def handle_hotmaps_results(permutation_result):
    """Takes in output from multiprocess_permutation function and converts to
    a better formatted dataframe.

    Parameters
    ----------
    permutation_result : list
        output from multiprocess_permutation

    Returns
    -------
    permutation_df : pd.DataFrame
        formatted output suitable to save
    """
    if len(permutation_result[0])  == 6:
        mycols = ['gene', 'window length', 'codon position', 'mutation count',
                  'windowed sum', 'p-value']
    else:
        mycols = ['gene', 'window length', 'codon position', 'index', 'mutation count',
                  'windowed sum', 'p-value']

    permutation_df = pd.DataFrame(permutation_result, columns=mycols)

    # get benjamani hochberg adjusted p-values
    permutation_df['q-value'] = 1
    for w in permutation_df['window length'].unique():
        is_window = permutation_df['window length'] == w
        permutation_df.loc[is_window, 'q-value'] = mypval.bh_fdr(permutation_df.loc[is_window, 'p-value'])
    #permutation_df['q-value'] = mypval.bh_fdr(permutation_df['p-value'])

    # order output
    #permutation_df = permutation_df.set_index('gene', drop=False)  # make sure genes are indices
    col_order = mycols + ['q-value']
    permutation_df = permutation_df.sort_values(by=['window length', 'p-value'])
    return permutation_df[col_order]


Instruction:
Here you have a function in Python 3, explain what it does
def handle_protein_results(permutation_result):
    mycols = ['gene', 'num recurrent', 'normalized graph-smoothed position entropy',
              'normalized graph-smoothed position entropy p-value',
              'Total Mutations', 'Unmapped to Ref Tx']
    permutation_df = pd.DataFrame(permutation_result, columns=mycols)

    # get benjamani hochberg adjusted p-values
    permutation_df['normalized graph-smoothed position entropy BH q-value'] = mypval.bh_fdr(permutation_df['normalized graph-smoothed position entropy p-value'])

    # order output
    permutation_df = permutation_df.set_index('gene', drop=False)  # make sure genes are indices
    col_order = ['gene', 'Total Mutations', 'Unmapped to Ref Tx',
                 'num recurrent',
                 'normalized graph-smoothed position entropy',
                 'normalized graph-smoothed position entropy p-value',
                 'normalized graph-smoothed position entropy BH q-value']
    permutation_df = permutation_df.sort_values(by=['normalized graph-smoothed position entropy p-value'])
    return permutation_df[col_order]

Response:
Takes in output from multiprocess_permutation function and converts to
    a better formatted dataframe.


Instruction:
Can you generate the documentation for the following Python 3 function
def handle_effect_results(permutation_result):
    mycols = ['gene', 'num recurrent', 'num inactivating', 'entropy-on-effect',
              'entropy-on-effect p-value',
              'Total Mutations', 'Unmapped to Ref Tx']
    permutation_df = pd.DataFrame(sorted(permutation_result, key=lambda x: x[4] if x[4] is not None else 1.1),
                                  columns=mycols)

    # get benjamani hochberg adjusted p-values
    permutation_df['entropy-on-effect BH q-value'] = mypval.bh_fdr(permutation_df['entropy-on-effect p-value'])

    # order output
    permutation_df = permutation_df.set_index('gene', drop=False)  # make sure genes are indices
    permutation_df['num recurrent'] = permutation_df['num recurrent'].fillna(-1).astype(int)  # fix dtype isssue
    col_order = ['gene', 'Total Mutations', 'Unmapped to Ref Tx',
                 'num recurrent', 'num inactivating', 'entropy-on-effect',
                 'entropy-on-effect p-value', 'entropy-on-effect BH q-value']
    return permutation_df[col_order]

Response:
Takes in output from multiprocess_permutation function and converts to
    a better formatted dataframe.


Instruction:
How would you explain what the following Python 3 function does
def get_frameshift_info(fs_df, bins):
    fs_df = compute_indel_length(fs_df)

    # count the number INDELs with length non-dividable by 3
    num_indels = []
    indel_len = []
    num_categories = 0
    i = 1
    while(num_categories<bins):
        # not inframe length indel
        if i%3:
            if num_categories != bins-1:
                tmp_num = len(fs_df[fs_df['indel len']==i])
            else:
                tmp_num = len(fs_df[(fs_df['indel len']>=i) & ((fs_df['indel len']%3)>0)])
            num_indels.append(tmp_num)
            indel_len.append(i)
            num_categories += 1
        i += 1
    return indel_len, num_indels

Response: Counts the number of frameshifts stratified by a given length.


Instruction:
Can you generate the documentation for the following Python 3 function
def set_mutation_type(self, mut_type=''):
        if mut_type:
            # user specifies a mutation type
            self.mutation_type = mut_type
        else:
            # mutation type is taken from object attributes
            if not self.is_valid:
                # does not correctly fall into a category
                self.mutation_type = 'not valid'
            elif self.unknown_effect:
                self.mutation_type = 'unknown effect'
            elif self.is_no_protein:
                self.mutation_type = 'no protein'
            elif self.is_missing_info:
                # mutation has a ?
                self.mutation_type = 'missing'
            else:
                # valid mutation type to be counted
                if self.is_lost_stop:
                    self.mutation_type = 'Nonstop_Mutation'
                elif self.is_lost_start:
                    self.mutation_type = 'Translation_Start_Site'
                elif self.is_synonymous:
                    # synonymous must go before missense since mutations
                    # can be categorized as synonymous and missense. Although
                    # in reality such cases are actually synonymous and not
                    # missense mutations.
                    self.mutation_type = 'Silent'
                elif self.is_missense:
                    self.mutation_type = 'Missense_Mutation'
                elif self.is_indel:
                    self.mutation_type = 'In_Frame_Indel'
                elif self.is_nonsense_mutation:
                    self.mutation_type = 'Nonsense_Mutation'
                elif self.is_frame_shift:
                    self.mutation_type = 'Frame_Shift_Indel'

Response: Sets the mutation type attribute to a single label based on the attribute flags.


Instruction:
Can you write a function in Python 3 where it
sets amino acid change and position.

Response:
def set_amino_acid(self, aa):
        """Set amino acid change and position."""
        aa = aa.upper()  # make sure it is upper case
        aa = aa[2:] if aa.startswith('P.') else aa  # strip "p."
        self.__set_mutation_status()  # set flags detailing the type of mutation
        self.__parse_hgvs_syntax(aa)


Instruction:
Can you tell what is the following Python 3 function doing
def __set_mutation_type(self, hgvs_string):
        self.__set_lost_stop_status(hgvs_string)
        self.__set_lost_start_status(hgvs_string)
        self.__set_missense_status(hgvs_string)  # missense mutations
        self.__set_indel_status()  # indel mutations
        self.__set_frame_shift_status()  # check for fs
        self.__set_premature_stop_codon_status(hgvs_string)

Response: Interpret the mutation type and set appropriate flags.


Instruction:
How would you implement a function in Python 3 that
sets the self. is_missense flag.

Response:
def __set_missense_status(self, hgvs_string):
        """Sets the self.is_missense flag."""
        # set missense status
        if re.search('^[A-Z?]\d+[A-Z?]$', hgvs_string):
            self.is_missense = True
            self.is_non_silent = True
        else:
            self.is_missense = False


Instruction:
Explain what the following Python 3 code does
def __set_lost_start_status(self, hgvs_string):
        # set is lost start status
        mymatch = re.search('^([A-Z?])(\d+)([A-Z?])$', hgvs_string)
        if mymatch:
            grps = mymatch.groups()
            if int(grps[1]) == 1 and grps[0] != grps[2]:
                self.is_lost_start = True
                self.is_non_silent = True
            else:
                self.is_lost_start = False
        else:
            self.is_lost_start = False

Response: Sets the self. is_lost_start flag.


Instruction:
Make a summary of the following Python 3 code
def __set_frame_shift_status(self):
        if 'fs' in self.hgvs_original:
            self.is_frame_shift = True
            self.is_non_silent = True
        elif re.search('[A-Z]\d+[A-Z]+\*', self.hgvs_original):
            # it looks like some mutations dont follow the convention
            # of using 'fs' to indicate frame shift
            self.is_frame_shift = True
            self.is_non_silent = True
        else:
            self.is_frame_shift = False

Response: Check for frame shift and set the self. is_frame_shift flag.


Instruction:
Write a Python 3 script to
check if the stop codon was mutated to something other than a stop codon.

Response:
def __set_lost_stop_status(self, hgvs_string):
        """Check if the stop codon was mutated to something other than
        a stop codon."""
        lost_stop_pattern = '^\*\d+[A-Z?]+\*?$'
        if re.search(lost_stop_pattern, hgvs_string):
            self.is_lost_stop = True
            self.is_non_silent = True
        else:
            self.is_lost_stop = False


Instruction:
Given the following Python 3 function, write the documentation
def __set_premature_stop_codon_status(self, hgvs_string):
        if re.search('.+\*(\d+)?$', hgvs_string):
            self.is_premature_stop_codon = True
            self.is_non_silent = True

            # check if it is also a nonsense mutation
            if hgvs_string.endswith('*'):
                self.is_nonsense_mutation = True
            else:
                self.is_nonsense_mutation = False
        else:
            self.is_premature_stop_codon = False
            self.is_nonsense_mutation = False

Response: Set whether there is a premature stop codon.


Instruction:
Here you have a function in Python 3, explain what it does
def __set_indel_status(self):
        # set indel status
        if "ins" in self.hgvs_original:
            # mutation is insertion
            self.is_insertion = True
            self.is_deletion = False
            self.is_indel = True
            self.is_non_silent = True
        elif "del" in self.hgvs_original:
            # mutation is deletion
            self.is_deletion = True
            self.is_insertion = False
            self.is_indel = True
            self.is_non_silent = True
        else:
            # not an indel
            self.is_deletion = False
            self.is_insertion = False
            self.is_indel = False

Response: Sets the status of the indel in the current state of the mutation being an indel.


Instruction:
Write a Python 3 function for
setting a flag for unkown effect according to HGVS syntax.

Response:
def __set_unkown_effect(self, hgvs_string):
        """Sets a flag for unkown effect according to HGVS syntax. The
        COSMIC database also uses unconventional questionmarks to denote
        missing information.

        Args:
            hgvs_string (str): hgvs syntax with "p." removed
        """
        # Standard use by HGVS of indicating unknown effect.
        unknown_effect_list = ['?', '(=)', '=']  # unknown effect symbols
        if hgvs_string in unknown_effect_list:
            self.unknown_effect = True
        elif "(" in hgvs_string:
            # parethesis in HGVS indicate expected outcomes
            self.unknown_effect = True
        else:
            self.unknown_effect = False

        # detect if there are missing information. commonly COSMIC will
        # have insertions with p.?_?ins? or deleteions with ?del indicating
        # missing information.
        if "?" in hgvs_string:
            self.is_missing_info = True
        else:
            self.is_missing_info = False


Instruction:
Explain what the following Python 3 code does
def __set_no_protein(self, hgvs_string):
        no_protein_list = ['0', '0?']  # no protein symbols
        if hgvs_string in no_protein_list:
            self.is_no_protein = True
            self.is_non_silent = True
        else:
            self.is_no_protein = False

Response: Set a flag for no protein expected.


Instruction:
Can you implement a function in Python 3 that
converts HGVS syntax into attributes.

Response:
def __parse_hgvs_syntax(self, aa_hgvs):
        """Convert HGVS syntax for amino acid change into attributes.

        Specific details of the mutation are stored in attributes like
        self.intial (prior to mutation), sel.pos (mutation position),
        self.mutated (mutation), and self.stop_pos (position of stop codon,
        if any).

        Args:
            aa_hgvs (str): amino acid string following HGVS syntax
        """
        self.is_valid = True  # assume initially the syntax is legitimate
        self.is_synonymous = False  # assume not synonymous until proven
        if self.unknown_effect or self.is_no_protein:
            # unknown effect from mutation. usually denoted as p.?
            self.pos = None
            pass
        elif self.is_lost_stop:
            self.initial = aa_hgvs[0]
            self.mutated = re.findall('([A-Z?*]+)$', aa_hgvs)[0]
            self.pos = int(re.findall('^\*(\d+)', aa_hgvs)[0])
            self.stop_pos = None
        elif self.is_lost_start:
            self.initial = aa_hgvs[0]
            self.mutated = aa_hgvs[-1]
            self.pos = int(aa_hgvs[1:-1])
        elif self.is_missense:
            self.initial = aa_hgvs[0]
            self.mutated = aa_hgvs[-1]
            self.pos = int(aa_hgvs[1:-1])
            self.stop_pos = None  # not a nonsense mutation
            if self.initial == self.mutated:
                self.is_synonymous = True
                self.is_non_silent = False
            elif self.mutated == '*':
                self.is_nonsense_mutation = True
        elif self.is_indel:
            if self.is_insertion:
                if not self.is_missing_info:
                    self.initial = re.findall('([A-Z])\d+', aa_hgvs)[:2]  # first two
                    self.pos = tuple(map(int, re.findall('[A-Z](\d+)', aa_hgvs)[:2]))  # first two
                    self.mutated = re.findall('(?<=INS)[A-Z0-9?*]+', aa_hgvs)[0]
                    self.mutated = self.mutated.strip('?')  # remove the missing info '?'
                else:
                    self.initial = ''
                    self.pos = tuple()
                    self.mutated = ''
            elif self.is_deletion:
                if not self.is_missing_info:
                    self.initial = re.findall('([A-Z])\d+', aa_hgvs)
                    self.pos = tuple(map(int, re.findall('[A-Z](\d+)', aa_hgvs)))
                    self.mutated = re.findall('(?<=DEL)[A-Z]*', aa_hgvs)[0]
                else:
                    self.initial = ''
                    self.pos = tuple()
                    self.mutated = ''
        elif self.is_frame_shift:
            self.initial = aa_hgvs[0]
            self.mutated = ''
            try:
                self.pos = int(re.findall('[A-Z*](\d+)', aa_hgvs)[0])
                if self.is_premature_stop_codon:
                    self.stop_pos = int(re.findall('\*>?(\d+)$', aa_hgvs)[0])
                else:
                    self.stop_pos = None
            except IndexError:
                # unconventional usage of indicating frameshifts will cause
                # index errors. For example, in some cases 'fs' is not used.
                # In other cases, either amino acids were not included or
                # just designated as a '?'
                self.logger.debug('(Parsing-Problem) frame shift hgvs string: "%s"' % aa_hgvs)
                self.pos = None
                self.stop_pos = None
                self.is_missing_info = True
        elif self.is_nonsense_mutation:
            self.initial = aa_hgvs[0]
            self.mutated = '*'  # there is actually a stop codon
            self.stop_pos = 0  # indicates same position is stop codon
            try:
                self.pos = int(aa_hgvs[1:-1])
            except ValueError:
                # wierd error of p.E217>D*
                self.is_valid = False
                self.pos = None
                self.logger.debug('(Parsing-Problem) Invalid HGVS Amino Acid '
                                  'syntax: ' + aa_hgvs)
            if self.initial == self.mutated:
                # classify nonsense-to-nonsense mutations as synonymous
                self.is_synonymous = True
                self.is_non_silent = False
        else:
            self.is_valid = False  # did not match any of the possible cases
            self.logger.debug('(Parsing-Problem) Invalid HGVS Amino Acid '
                              'syntax: ' + aa_hgvs)


Instruction:
Write a Python 3 function that can
perform null - permutations for the given set of null mutations for a single gene.

Response:
def deleterious_permutation(obs_del,
                            context_counts,
                            context_to_mut,
                            seq_context,
                            gene_seq,
                            num_permutations=10000,
                            stop_criteria=100,
                            pseudo_count=0,
                            max_batch=25000):
    """Performs null-permutations for deleterious mutation statistics
    in a single gene.

    Parameters
    ----------
    context_counts : pd.Series
        number of mutations for each context
    context_to_mut : dict
        dictionary mapping nucleotide context to a list of observed
        somatic base changes.
    seq_context : SequenceContext
        Sequence context for the entire gene sequence (regardless
        of where mutations occur). The nucleotide contexts are
        identified at positions along the gene.
    gene_seq : GeneSequence
        Sequence of gene of interest
    num_permutations : int, default: 10000
        number of permutations to create for null
    pseudo_count : int, default: 0
        Pseudo-count for number of deleterious mutations for each
        permutation of the null distribution. Increasing pseudo_count
        makes the statistical test more stringent.

    Returns
    -------
    del_count_list : list
        list of deleterious mutation counts under the null
    """
    mycontexts = context_counts.index.tolist()
    somatic_base = [base
                    for one_context in mycontexts
                    for base in context_to_mut[one_context]]

    # calculate the # of batches for simulations
    max_batch = min(num_permutations, max_batch)
    num_batches = num_permutations // max_batch
    remainder = num_permutations % max_batch
    batch_sizes = [max_batch] * num_batches
    if remainder:
        batch_sizes += [remainder]

    num_sim = 0
    null_del_ct = 0
    for j, batch_size in enumerate(batch_sizes):
        # stop iterations if reached sufficient precision
        if null_del_ct >= stop_criteria:
            #j = j - 1
            break

        # get random positions determined by sequence context
        tmp_contxt_pos = seq_context.random_pos(context_counts.iteritems(),
                                                batch_size)
        tmp_mut_pos = np.hstack(pos_array for base, pos_array in tmp_contxt_pos)

        # determine result of random positions
        for i, row in enumerate(tmp_mut_pos):
            # get info about mutations
            tmp_mut_info = mc.get_aa_mut_info(row,
                                              somatic_base,
                                              gene_seq)

            # calc deleterious mutation info
            tmp_del_count = cutils.calc_deleterious_info(tmp_mut_info['Reference AA'],
                                                         tmp_mut_info['Somatic AA'],
                                                         tmp_mut_info['Codon Pos'])

            # update empricial null distribution
            if tmp_del_count >= obs_del: null_del_ct += 1

            # stop if reach sufficient precision on p-value
            if null_del_ct >= stop_criteria:
                break
        # update number of simulations
        num_sim += i + 1

    #num_sim = j*max_batch + i+1
    del_pval = float(null_del_ct) / (num_sim)

    return del_pval


Instruction:
Write a Python 3 script for
performing null - permutations for position - based mutation statistics in a single gene.

Response:
def position_permutation(obs_stat,
                         context_counts,
                         context_to_mut,
                         seq_context,
                         gene_seq,
                         gene_vest=None,
                         num_permutations=10000,
                         stop_criteria=100,
                         pseudo_count=0,
                         max_batch=25000):
    """Performs null-permutations for position-based mutation statistics
    in a single gene.

    Parameters
    ----------
    obs_stat : tuple, (recur ct, entropy, delta entropy, mean vest)
        tuple containing the observed statistics
    context_counts : pd.Series
        number of mutations for each context
    context_to_mut : dict
        dictionary mapping nucleotide context to a list of observed
        somatic base changes.
    seq_context : SequenceContext
        Sequence context for the entire gene sequence (regardless
        of where mutations occur). The nucleotide contexts are
        identified at positions along the gene.
    gene_seq : GeneSequence
        Sequence of gene of interest
    num_permutations : int, default: 10000
        number of permutations to create for null
    stop_criteria : int
        stop after stop_criteria iterations are more significant
        then the observed statistic.
    pseudo_count : int, default: 0
        Pseudo-count for number of recurrent missense mutations for each
        permutation for the null distribution. Increasing pseudo_count
        makes the statistical test more stringent.

    Returns
    -------
    num_recur_list : list
        list of recurrent mutation counts under the null
    entropy_list : list
        list of position entropy values under the null
    """
    # get contexts and somatic base
    mycontexts = context_counts.index.tolist()
    somatic_base = [base
                    for one_context in mycontexts
                    for base in context_to_mut[one_context]]

    # calculate the # of batches for simulations
    max_batch = min(num_permutations, max_batch)
    num_batches = num_permutations // max_batch
    remainder = num_permutations % max_batch
    batch_sizes = [max_batch] * num_batches
    if remainder:
        batch_sizes += [remainder]

    obs_recur, obs_ent, obs_delta_ent, obs_vest = obs_stat
    num_sim = 0 # number of simulations
    null_num_recur_ct, null_entropy_ct, null_delta_entropy_ct, null_vest_ct = 0, 0, 0, 0
    for j, batch_size in enumerate(batch_sizes):
        # stop iterations if reached sufficient precision
        if null_vest_ct >= stop_criteria and null_entropy_ct >= stop_criteria:
            break

        # get random positions determined by sequence context
        tmp_contxt_pos = seq_context.random_pos(context_counts.iteritems(),
                                                batch_size)
        tmp_mut_pos = np.hstack(pos_array for base, pos_array in tmp_contxt_pos)

        # calculate position-based statistics as a result of random positions
        for i, row in enumerate(tmp_mut_pos):
            # get info about mutations
            tmp_mut_info = mc.get_aa_mut_info(row,
                                              somatic_base,
                                              gene_seq)

            # calculate position info
            tmp_recur_ct, tmp_entropy, tmp_delta_entropy, _ = cutils.calc_pos_info(tmp_mut_info['Codon Pos'],
                                                                                tmp_mut_info['Reference AA'],
                                                                                tmp_mut_info['Somatic AA'],
                                                                                pseudo_count=pseudo_count,
                                                                                is_obs=0)
            # get vest scores
            if gene_vest:
                tmp_vest = scores.compute_vest_stat(gene_vest,
                                                    tmp_mut_info['Reference AA'],
                                                    tmp_mut_info['Somatic AA'],
                                                    tmp_mut_info['Codon Pos'])
            else:
                tmp_vest = 0.0

            # update empirical null distribution counts
            if tmp_entropy-utils.epsilon <= obs_ent: null_entropy_ct += 1
            if tmp_vest+utils.epsilon >= obs_vest: null_vest_ct += 1

            # stop iterations if reached sufficient precision
            if null_vest_ct >= stop_criteria and null_entropy_ct >= stop_criteria:
                break
        # update the number of simulations
        num_sim += i+1

    # calculate p-value from empirical null-distribution
    ent_pval = float(null_entropy_ct) / (num_sim)
    vest_pval = float(null_vest_ct) / (num_sim)

    return ent_pval, vest_pval


Instruction:
Can you implement a function in Python 3 that
performs null - permutations for position - based mutation statistics in a single gene.

Response:
def hotmaps_permutation(obs_stat,
                        context_counts,
                        context_to_mut,
                        seq_context,
                        gene_seq,
                        window,
                        num_permutations=10000,
                        stop_criteria=100,
                        max_batch=25000,
                        null_save_path=None):
    """Performs null-permutations for position-based mutation statistics
    in a single gene.

    Parameters
    ----------
    obs_stat : dict
        dictionary mapping codons to the sum of mutations in a window
    context_counts : pd.Series
        number of mutations for each context
    context_to_mut : dict
        dictionary mapping nucleotide context to a list of observed
        somatic base changes.
    seq_context : SequenceContext
        Sequence context for the entire gene sequence (regardless
        of where mutations occur). The nucleotide contexts are
        identified at positions along the gene.
    gene_seq : GeneSequence
        Sequence of gene of interest
    window : int
        Number of codons to the left/right of a mutated position to consider
        in the window
    num_permutations : int, default: 10000
        number of permutations to create for null
    stop_criteria : int
        stop after stop_criteria iterations are more significant
        then the observed statistic.
    max_batch : int
        maximum number of whole gene simulations to do at once.
        For large number of simulations holding a matrix of M x N,
        where M is the number of mutations and N is the number of simulations,
        can get quite large.
    null_save_path : str or None
        File path to save null distribution. If None, don't save it.

    Returns
    -------
    pvals : dict
        Maps mutated codon position to the calculated p-value
    """
    # get contexts and somatic base
    mycontexts = context_counts.index.tolist()
    somatic_base = [base
                    for one_context in mycontexts
                    for base in context_to_mut[one_context]]

    # calculate the # of batches for simulations
    max_batch = min(num_permutations, max_batch)
    num_batches = num_permutations // max_batch
    remainder = num_permutations % max_batch
    batch_sizes = [max_batch] * num_batches
    if remainder:
        batch_sizes += [remainder]

    # figure out which position has highest value
    max_key = {w: max(obs_stat[w], key=(lambda key: obs_stat[w][key]))
               for w in window}

    # setup null dist counts
    null_cts = {w: {k: 0 for k in obs_stat[w]}
                for w in window }

    # empirical null distribution (saved if file path provided)
    empirical_null = {w: {} for w in window}

    num_sim = 0 # number of simulations
    for j, batch_size in enumerate(batch_sizes):
        # stop iterations if reached sufficient precision
        # stop iterations if reached sufficient precision
        stop_flag = [(null_cts[w][max_key[w]]>=stop_criteria)
                      for w in window]
        if all(stop_flag):
            break
        #if null_cts[max_key] >= stop_criteria:
            #break

        # get random positions determined by sequence context
        tmp_contxt_pos = seq_context.random_pos(context_counts.iteritems(),
                                                batch_size)
        tmp_mut_pos = np.hstack(pos_array for base, pos_array in tmp_contxt_pos)

        # calculate position-based statistics as a result of random positions
        for i, row in enumerate(tmp_mut_pos):
            # get info about mutations
            tmp_mut_info = mc.get_aa_mut_info(row,
                                              somatic_base,
                                              gene_seq)

            # calculate position info
            tmp_pos, tmp_sim = utils.calc_windowed_sum(tmp_mut_info['Codon Pos'],
                                                 tmp_mut_info['Reference AA'],
                                                 tmp_mut_info['Somatic AA'],
                                                 window)

            # update the counts when the empirical null passes the observed
            for tmp_w in tmp_sim:
                for tmp_key in tmp_sim[tmp_w]:
                    # get mutation count for simulation
                    val = tmp_sim[tmp_w][tmp_key]

                    # add to empirical null distribution
                    empirical_null[tmp_w].setdefault(val, 0)
                    empirical_null[tmp_w][val] += 1

                    # update counts used for p-value
                    for key in null_cts[tmp_w]:
                        if val >= obs_stat[tmp_w][key]:
                            null_cts[tmp_w][key] += 1

            # update the number of simulations
            num_sim += len(tmp_pos)

            # stop iterations if reached sufficient precision
            stop_flag = [(null_cts[w][max_key[w]]>=stop_criteria)
                         for w in window]
            if all(stop_flag):
                break

    # calculate p-value from empirical null-distribution
    pvals = {w: {k: float(null_cts[w][k]) / (num_sim) for k in obs_stat[w]}
             for w in window}

    # save empirical distribution
    if null_save_path:
        for w in window:
            # create null distribution
            output = [['mutation_count', 'p-value']]
            sorted_cts = sorted(empirical_null[w].keys())
            tmp_sum = 0
            for i in range(len(sorted_cts)):
                tmp_sum += empirical_null[w][sorted_cts[-(i+1)]]
                tmp_pval = tmp_sum / float(num_sim)
                output.append([sorted_cts[-(i+1)], tmp_pval])
            # save output
            with open(null_save_path.format(w), 'w') as handle:
                mywriter = csv.writer(handle, delimiter='\t', lineterminator='\n')
                mywriter.writerows(output)

    return pvals


Instruction:
Can you generate a brief explanation for the following Python 3 code
def protein_permutation(graph_score,
                        num_codons_obs,
                        context_counts,
                        context_to_mut,
                        seq_context,
                        gene_seq,
                        gene_graph,
                        num_permutations=10000,
                        stop_criteria=100,
                        pseudo_count=0):
    """Performs null-simulations for position-based mutation statistics
    in a single gene.

    Parameters
    ----------
    graph_score : float
        clustering score for observed data
    num_codons_obs : int
        number of codons with missense mutation in observed data
    context_counts : pd.Series
        number of mutations for each context
    context_to_mut : dict
        dictionary mapping nucleotide context to a list of observed
        somatic base changes.
    seq_context : SequenceContext
        Sequence context for the entire gene sequence (regardless
        of where mutations occur). The nucleotide contexts are
        identified at positions along the gene.
    gene_seq : GeneSequence
        Sequence of gene of interest
    num_permutations : int, default: 10000
        number of permutations to create for null
    stop_criteria : int
        stop after stop_criteria iterations are more significant
        then the observed statistic.

    Returns
    -------
    protein_pval : float
        p-value for clustering in neighbor graph constructure from protein
        structures
    """
    # get contexts and somatic base
    mycontexts = context_counts.index.tolist()
    somatic_base = [base
                    for one_context in mycontexts
                    for base in context_to_mut[one_context]]

    # get random positions determined by sequence context
    tmp_contxt_pos = seq_context.random_pos(context_counts.iteritems(),
                                            num_permutations)
    tmp_mut_pos = np.hstack(pos_array for base, pos_array in tmp_contxt_pos)

    # calculate position-based statistics as a result of random positions
    null_graph_entropy_ct = 0
    coverage_list = []
    num_mut_list = []
    graph_entropy_list = []
    for i, row in enumerate(tmp_mut_pos):
        # calculate the expected value of the relative increase in coverage
        if i == stop_criteria-1:
            rel_inc = [coverage_list[k] / float(num_mut_list[k])
                       for k in range(stop_criteria-1)
                       if coverage_list[k]]
            exp_rel_inc = np.mean(rel_inc)

            # calculate observed statistic
            if num_codons_obs:
                obs_stat = graph_score / np.log2(exp_rel_inc*num_codons_obs)
            else:
                obs_stat = 1.0

            # calculate statistics for simulated data
            sim_stat_list = [ent / np.log2(exp_rel_inc*num_mut_list[l])
                             for l, ent in enumerate(graph_entropy_list)]
            null_graph_entropy_ct = len([s for s in sim_stat_list
                                         if s-utils.epsilon <= obs_stat])

        # get info about mutations
        tmp_mut_info = mc.get_aa_mut_info(row,
                                          somatic_base,
                                          gene_seq)

        # calculate position info
        tmp_tuple = cutils.calc_pos_info(tmp_mut_info['Codon Pos'],
                                         tmp_mut_info['Reference AA'],
                                         tmp_mut_info['Somatic AA'],
                                         pseudo_count=pseudo_count,
                                         is_obs=0)
        _, _, _, tmp_pos_ct = tmp_tuple

        # record num of mut codons
        if i < stop_criteria-1:
            tmp_num_mut_codons = len(tmp_pos_ct)
            num_mut_list.append(tmp_num_mut_codons)

        # get entropy on graph-smoothed probability distribution
        tmp_graph_entropy, tmp_coverage = scores.compute_ng_stat(gene_graph, tmp_pos_ct)

        # record the "coverage" in the graph
        if i < stop_criteria-1:
            coverage_list.append(tmp_coverage)
            graph_entropy_list.append(tmp_graph_entropy)

        # update empirical null distribution counts
        if i >= stop_criteria:
            #if tmp_graph_entropy-utils.epsilon <= graph_score:
            if tmp_num_mut_codons:
                sim_stat = tmp_graph_entropy / np.log2(exp_rel_inc*tmp_num_mut_codons)
            else:
                sim_stat = 1.0

            # add count
            if sim_stat-utils.epsilon <= obs_stat:
                null_graph_entropy_ct += 1

        # stop iterations if reached sufficient precision
        if null_graph_entropy_ct >= stop_criteria:
            break

    # calculate p-value from empirical null-distribution
    protein_pval = float(null_graph_entropy_ct) / (i+1)

    return protein_pval, obs_stat

Response: Performs null - simulations for position - based mutation statistics in a single gene.


Instruction:
Can you tell what is the following Python 3 function doing
def effect_permutation(context_counts,
                       context_to_mut,
                       seq_context,
                       gene_seq,
                       num_permutations=10000,
                       pseudo_count=0):
    """Performs null-permutations for effect-based mutation statistics
    in a single gene.

    Parameters
    ----------
    context_counts : pd.Series
        number of mutations for each context
    context_to_mut : dict
        dictionary mapping nucleotide context to a list of observed
        somatic base changes.
    seq_context : SequenceContext
        Sequence context for the entire gene sequence (regardless
        of where mutations occur). The nucleotide contexts are
        identified at positions along the gene.
    gene_seq : GeneSequence
        Sequence of gene of interest
    num_permutations : int, default: 10000
        number of permutations to create for null
    pseudo_count : int, default: 0
        Pseudo-count for number of recurrent missense mutations for each
        permutation for the null distribution. Increasing pseudo_count
        makes the statistical test more stringent.

    Returns
    -------
    effect_entropy_list : list
        list of entropy of effect values under the null
    recur_list : list
        number of recurrent missense mutations
    inactivating_list : list
        number of inactivating mutations
    """
    mycontexts = context_counts.index.tolist()
    somatic_base = [base
                    for one_context in mycontexts
                    for base in context_to_mut[one_context]]

    # get random positions determined by sequence context
    tmp_contxt_pos = seq_context.random_pos(context_counts.iteritems(),
                                            num_permutations)
    tmp_mut_pos = np.hstack(pos_array for base, pos_array in tmp_contxt_pos)

    # calculate position-based statistics as a result of random positions
    effect_entropy_list, recur_list, inactivating_list = [], [], []
    for row in tmp_mut_pos:
        # get info about mutations
        tmp_mut_info = mc.get_aa_mut_info(row,
                                          somatic_base,
                                          gene_seq)

        # calculate position info
        tmp_entropy, tmp_recur, tmp_inactivating = cutils.calc_effect_info(tmp_mut_info['Codon Pos'],
                                                                           tmp_mut_info['Reference AA'],
                                                                           tmp_mut_info['Somatic AA'],
                                                                           pseudo_count=pseudo_count,
                                                                           is_obs=0)
        effect_entropy_list.append(tmp_entropy)
        recur_list.append(tmp_recur)
        inactivating_list.append(tmp_inactivating)

    return effect_entropy_list, recur_list, inactivating_list

Response: Performs null - permutations for effect - based mutation statistics in a single gene.


Instruction:
Here you have a function in Python 3, explain what it does
def non_silent_ratio_permutation(context_counts,
                                 context_to_mut,
                                 seq_context,
                                 gene_seq,
                                 num_permutations=10000):
    """Performs null-permutations for non-silent ratio across all genes.

    Parameters
    ----------
    context_counts : pd.Series
        number of mutations for each context
    context_to_mut : dict
        dictionary mapping nucleotide context to a list of observed
        somatic base changes.
    seq_context : SequenceContext
        Sequence context for the entire gene sequence (regardless
        of where mutations occur). The nucleotide contexts are
        identified at positions along the gene.
    gene_seq : GeneSequence
        Sequence of gene of interest
    num_permutations : int, default: 10000
        number of permutations to create for null

    Returns
    -------
    non_silent_count_list : list of tuples
        list of non-silent and silent mutation counts under the null
    """
    mycontexts = context_counts.index.tolist()
    somatic_base = [base
                    for one_context in mycontexts
                    for base in context_to_mut[one_context]]

    # get random positions determined by sequence context
    tmp_contxt_pos = seq_context.random_pos(context_counts.iteritems(),
                                            num_permutations)
    tmp_mut_pos = np.hstack(pos_array for base, pos_array in tmp_contxt_pos)

    # determine result of random positions
    non_silent_count_list = []
    for row in tmp_mut_pos:
        # get info about mutations
        tmp_mut_info = mc.get_aa_mut_info(row,
                                          somatic_base,
                                          gene_seq)

        # calc deleterious mutation info
        tmp_non_silent = cutils.calc_non_silent_info(tmp_mut_info['Reference AA'],
                                                     tmp_mut_info['Somatic AA'],
                                                     tmp_mut_info['Codon Pos'])
        non_silent_count_list.append(tmp_non_silent)
    return non_silent_count_list

Response: Performs null - permutations for non - silent ratio across all genes.


Instruction:
Can you generate the documentation for the following Python 3 function
def summary_permutation(context_counts,
                        context_to_mut,
                        seq_context,
                        gene_seq,
                        score_dir,
                        num_permutations=10000,
                        min_frac=0.0,
                        min_recur=2,
                        drop_silent=False):
    """Performs null-permutations and summarizes the results as features over
    the gene.

    Parameters
    ----------
    context_counts : pd.Series
        number of mutations for each context
    context_to_mut : dict
        dictionary mapping nucleotide context to a list of observed
        somatic base changes.
    seq_context : SequenceContext
        Sequence context for the entire gene sequence (regardless
        of where mutations occur). The nucleotide contexts are
        identified at positions along the gene.
    gene_seq : GeneSequence
        Sequence of gene of interest
    num_permutations : int, default: 10000
        number of permutations to create for null
    drop_silent : bool, default=False
        Flage on whether to drop all silent mutations. Some data sources
        do not report silent mutations, and the simulations should match this.

    Returns
    -------
    summary_info_list : list of lists
        list of non-silent and silent mutation counts under the null along
        with information on recurrent missense counts and missense positional
        entropy.
    """
    mycontexts = context_counts.index.tolist()
    somatic_base = [base
                    for one_context in mycontexts
                    for base in context_to_mut[one_context]]

    # get random positions determined by sequence context
    tmp_contxt_pos = seq_context.random_pos(context_counts.iteritems(),
                                            num_permutations)
    tmp_mut_pos = np.hstack(pos_array for base, pos_array in tmp_contxt_pos)

    # determine result of random positions
    gene_name = gene_seq.bed.gene_name
    gene_len = gene_seq.bed.cds_len
    summary_info_list = []
    for i, row in enumerate(tmp_mut_pos):
        # get info about mutations
        tmp_mut_info = mc.get_aa_mut_info(row,
                                          somatic_base,
                                          gene_seq)

        # Get all metrics summarizing each gene
        tmp_summary = cutils.calc_summary_info(tmp_mut_info['Reference AA'],
                                               tmp_mut_info['Somatic AA'],
                                               tmp_mut_info['Codon Pos'],
                                               gene_name,
                                               score_dir,
                                               min_frac=min_frac,
                                               min_recur=min_recur)

        # drop silent if needed
        if drop_silent:
            # silent mutation count is index 1
            tmp_summary[1] = 0

        # limit the precision of floats
        #pos_ent = tmp_summary[-1]
        #tmp_summary[-1] = '{0:.5f}'.format(pos_ent)

        summary_info_list.append([gene_name, i+1, gene_len]+tmp_summary)
    return summary_info_list

Response: Performs null - permutations and summarizes the results as features over the gene.


Instruction:
Can you generate the documentation for the following Python 3 function
def maf_permutation(context_counts,
                    context_to_mut,
                    seq_context,
                    gene_seq,
                    num_permutations=10000,
                    drop_silent=False):
    """Performs null-permutations across all genes and records the results in
    a format like a MAF file. This could be useful for examining the null
    permutations because the alternative approaches always summarize the results.
    With the simulated null-permutations, novel metrics can be applied to create
    an empirical null-distribution.

    Parameters
    ----------
    context_counts : pd.Series
        number of mutations for each context
    context_to_mut : dict
        dictionary mapping nucleotide context to a list of observed
        somatic base changes.
    seq_context : SequenceContext
        Sequence context for the entire gene sequence (regardless
        of where mutations occur). The nucleotide contexts are
        identified at positions along the gene.
    gene_seq : GeneSequence
        Sequence of gene of interest
    num_permutations : int, default: 10000
        number of permutations to create for null
    drop_silent : bool, default=False
        Flage on whether to drop all silent mutations. Some data sources
        do not report silent mutations, and the simulations should match this.

    Returns
    -------
    maf_list : list of tuples
        list of null mutations with mutation info in a MAF like format
    """
    mycontexts = context_counts.index.tolist()
    somatic_base, base_context = zip(*[(base, one_context)
                                       for one_context in mycontexts
                                       for base in context_to_mut[one_context]])

    # get random positions determined by sequence context
    tmp_contxt_pos = seq_context.random_pos(context_counts.iteritems(),
                                            num_permutations)
    tmp_mut_pos = np.hstack(pos_array for base, pos_array in tmp_contxt_pos)

    # info about gene
    gene_name = gene_seq.bed.gene_name
    strand = gene_seq.bed.strand
    chrom = gene_seq.bed.chrom
    gene_seq.bed.init_genome_coordinates()  # map seq pos to genome

    # determine result of random positions
    maf_list = []
    for row in tmp_mut_pos:
        # get genome coordinate
        pos2genome = np.vectorize(lambda x: gene_seq.bed.seqpos2genome[x]+1)
        genome_coord = pos2genome(row)

        # get info about mutations
        tmp_mut_info = mc.get_aa_mut_info(row,
                                          somatic_base,
                                          gene_seq)

        # get string describing variant
        var_class = cutils.get_variant_classification(tmp_mut_info['Reference AA'],
                                                      tmp_mut_info['Somatic AA'],
                                                      tmp_mut_info['Codon Pos'])

        # prepare output
        for k, mysomatic_base in enumerate(somatic_base):
            # format DNA change
            ref_nuc = tmp_mut_info['Reference Nuc'][k]
            nuc_pos = row[k]
            dna_change = 'c.{0}{1}>{2}'.format(ref_nuc, nuc_pos, mysomatic_base)

            # format protein change
            ref_aa = tmp_mut_info['Reference AA'][k]
            somatic_aa = tmp_mut_info['Somatic AA'][k]
            codon_pos = tmp_mut_info['Codon Pos'][k]
            protein_change = 'p.{0}{1}{2}'.format(ref_aa, codon_pos, somatic_aa)

            # reverse complement if on negative strand
            if strand == '-':
                ref_nuc = utils.rev_comp(ref_nuc)
                mysomatic_base = utils.rev_comp(mysomatic_base)

            # append results
            if drop_silent and var_class[k].decode() == 'Silent': continue
            maf_line = [gene_name, strand, chrom, genome_coord[k], genome_coord[k],
                        ref_nuc, mysomatic_base, base_context[k], dna_change,
                        protein_change, var_class[k].decode()]
            maf_list.append(maf_line)

    return maf_list

Response: Performs null - permutations across all genes and records the results in a MAF file.


Instruction:
Explain what the following Python 3 code does
def markdown(value, extensions=settings.MARKDOWN_EXTENSIONS,
             extension_configs=settings.MARKDOWN_EXTENSION_CONFIGS,
             safe=False):
    """ Render markdown over a given value, optionally using varios extensions.

    Default extensions could be defined which MARKDOWN_EXTENSIONS option.

    :returns: A rendered markdown

    """
    return mark_safe(markdown_module.markdown(
        force_text(value), extensions=extensions,
        extension_configs=extension_configs, safe_mode=safe))

Response: Render a given value optionally using varios extensions.


Instruction:
How would you code a function in Python 3 to
return script tag with initialization code.

Response:
def editor_js_initialization(selector, **extra_settings):
    """ Return script tag with initialization code. """

    init_template = loader.get_template(
        settings.MARKDOWN_EDITOR_INIT_TEMPLATE)

    options = dict(
        previewParserPath=reverse('django_markdown_preview'),
        **settings.MARKDOWN_EDITOR_SETTINGS)
    options.update(extra_settings)
    ctx = dict(
        selector=selector,
        extra_settings=simplejson.dumps(options)
    )
    return init_template.render(ctx)


Instruction:
Can you generate a brief explanation for the following Python 3 code
def preview(request):
    if settings.MARKDOWN_PROTECT_PREVIEW:
        user = getattr(request, 'user', None)
        if not user or not user.is_staff:
            from django.contrib.auth.views import redirect_to_login
            return redirect_to_login(request.get_full_path())

    return render(
        request, settings.MARKDOWN_PREVIEW_TEMPLATE, dict(
            content=request.POST.get('data', 'No content posted'),
            css=settings.MARKDOWN_STYLE
        ))

Response:
Render preview page.

    :returns: A rendered preview


Instruction:
How would you explain what the following Python 3 function does
def register():

    admin.site.unregister(FlatPage)
    admin.site.register(FlatPage, LocalFlatPageAdmin)

Response: Register markdown for flatpages.


Instruction:
Can you generate the documentation for the following Python 3 function
def markdown(value, arg=None):
    extensions = (arg and arg.split(',')) or settings.MARKDOWN_EXTENSIONS
    return _markdown(value, extensions=extensions, safe=False)

Response: Render a given value using the MARKDOWN_EXTENSIONS setting.


Instruction:
Can you create a Python 3 function that
renders a given value optionally using MARKDOWN_EXTENSIONS.

Response:
def markdown_safe(value, arg=None):
    """ Render markdown over a given value, optionally using varios extensions.

    Default extensions could be defined which MARKDOWN_EXTENSIONS option.

    Enables safe mode, which strips raw HTML and only returns HTML generated
    by markdown.

    :returns: A rendered markdown.

    """
    extensions = (arg and arg.split(',')) or settings.MARKDOWN_EXTENSIONS
    return _markdown(value, extensions=extensions, safe=True)


Instruction:
Given the following Python 3 function, write the documentation
def markdown_editor(selector):
    return dict(
        selector=selector,
        extra_settings=mark_safe(simplejson.dumps(
            dict(previewParserPath=reverse('django_markdown_preview')))))

Response: Enable markdown editor for given textarea.


Instruction:
Can you generate the documentation for the following Python 3 function
def markdown_media_css():
    return dict(
        CSS_SET=posixpath.join(
            settings.MARKDOWN_SET_PATH, settings.MARKDOWN_SET_NAME, 'style.css'
        ),
        CSS_SKIN=posixpath.join(
            'django_markdown', 'skins', settings.MARKDOWN_EDITOR_SKIN,
            'style.css'
        )
    )

Response: Add css requirements to HTML.


Instruction:
Implement a Python 3 function for
converting given source from format to another.

Response:
def convert(source, to, format=None, extra_args=(), encoding='utf-8'):
    """Convert given `source` from `format` `to` another.

    `source` may be either a file path or a string to be converted.
    It's possible to pass `extra_args` if needed.  In case `format` is not
    provided, it will try to invert the format based on given `source`.

    Raises OSError if pandoc is not found! Make sure it has been installed and
    is available at path.

    """
    return _convert(
        _read_file, _process_file,
        source, to,
        format, extra_args,
        encoding=encoding)


Instruction:
Given the following Python 3 function, write the documentation
def get_pandoc_formats():
    try:
        p = subprocess.Popen(
            ['pandoc', '-h'],
            stdin=subprocess.PIPE,
            stdout=subprocess.PIPE)
    except OSError:
        raise OSError("You probably do not have pandoc installed.")

    help_text = p.communicate()[0].decode().splitlines(False)
    txt = ' '.join(help_text[1:help_text.index('Options:')])

    aux = txt.split('Output formats: ')
    in_ = aux[0].split('Input formats: ')[1].split(',')
    out = aux[1].split(',')

    return [f.strip() for f in in_], [f.strip() for f in out]

Response:
Dynamic preprocessor for Pandoc formats.
    Return 2 lists. from_formats and to_formats.


Instruction:
Explain what the following Python 3 code does
def render(self, name, value, attrs=None, renderer=None):
        html = super(MarkdownWidget, self).render(name, value, attrs, renderer)
        attrs = self.build_attrs(attrs)
        html += editor_js_initialization("#%s" % attrs['id'])
        return mark_safe(html)

Response: Render the tag with the necessary initialization.


Instruction:
Given the following Python 3 function, write the documentation
def extendMarkdown(self, md, md_globals):
        md.registerExtension(self)

        md.preprocessors.add('graphviz_block',
                             InlineGraphvizPreprocessor(md),
                             "_begin")

Response: Add InlineGraphvizPreprocessor to the Markdown instance.


Instruction:
Can you tell what is the following Python 3 function doing
def run(self, lines):

        text = "\n".join(lines)
        while 1:
            m = BLOCK_RE.search(text)
            if m:
                command = m.group('command')
                # Whitelist command, prevent command injection.
                if command not in SUPPORTED_COMMAMDS:
                    raise Exception('Command not supported: %s' % command)
                filename = m.group('filename')
                content = m.group('content')
                filetype = filename[filename.rfind('.')+1:]

                args = [command, '-T'+filetype]
                try:
                    proc = subprocess.Popen(
                        args,
                        stdin=subprocess.PIPE,
                        stderr=subprocess.PIPE,
                        stdout=subprocess.PIPE)
                    proc.stdin.write(content.encode('utf-8'))

                    output, err = proc.communicate()

                    if filetype == 'svg':
                        data_url_filetype = 'svg+xml'
                        encoding = 'utf-8'
                        img = output.decode(encoding)

                    if filetype == 'png':
                        data_url_filetype = 'png'
                        encoding = 'base64'
                        output = base64.b64encode(output)
                        data_path = "data:image/%s;%s,%s" % (
                            data_url_filetype,
                            encoding,
                            output)
                        img = "![" + filename + "](" + data_path + ")"

                    text = '%s\n%s\n%s' % (
                        text[:m.start()], img, text[m.end():])

                except Exception as e:
                        err = str(e) + ' : ' + str(args)
                        return (
                            '
Error : ' + err + '
'
                            '
' + content + '
').split('\n')

            else:
                break
        return text.split("\n")

Response: Match and generate dot code blocks.


Instruction:
Can you implement a function in Python 3 that
posts data to API.

Response:
def post(self, command, data=None):
        """Post data to API."""
        now = calendar.timegm(datetime.datetime.now().timetuple())
        if now > self.expiration:
            auth = self.__open("/oauth/token", data=self.oauth)
            self.__sethead(auth['access_token'])
        return self.__open("%s%s" % (self.api, command),
                           headers=self.head, data=data)


Instruction:
Here you have a function in Python 3, explain what it does
def __open(self, url, headers=None, data=None, baseurl=""):
        headers = headers or {}
        if not baseurl:
            baseurl = self.baseurl
        req = Request("%s%s" % (baseurl, url), headers=headers)
        _LOGGER.debug(url)

        try:
            req.data = urlencode(data).encode('utf-8')
        except TypeError:
            pass
        opener = build_opener()

        try:
            resp = opener.open(req)
            charset = resp.info().get('charset', 'utf-8')
            data = json.loads(resp.read().decode(charset))
            opener.close()
            _LOGGER.debug(json.dumps(data))
            return data
        except HTTPError as exception_:
            if exception_.code == 408:
                _LOGGER.debug("%s", exception_)
                return False
            raise TeslaException(exception_.code)

Response: Use raw urlopen command.


Instruction:
Can you implement a function in Python 3 that
updates the parking brake sensor.

Response:
def update(self):
        """Update the parking brake sensor."""
        self._controller.update(self._id, wake_if_asleep=False)
        data = self._controller.get_drive_params(self._id)
        if data:
            if not data['shift_state'] or data['shift_state'] == 'P':
                self.__state = True
            else:
                self.__state = False


Instruction:
Can you implement a function in Python 3 that
updates the HVAC state.

Response:
def update(self):
        """Update the HVAC state."""
        self._controller.update(self._id, wake_if_asleep=False)

        data = self._controller.get_climate_params(self._id)
        if data:
            if time.time() - self.__manual_update_time > 60:
                self.__is_auto_conditioning_on = (data
                                                  ['is_auto_conditioning_on'])
                self.__is_climate_on = data['is_climate_on']
                self.__driver_temp_setting = (data['driver_temp_setting']
                                              if data['driver_temp_setting']
                                              else self.__driver_temp_setting)
                self.__passenger_temp_setting = (data['passenger_temp_setting']
                                                 if
                                                 data['passenger_temp_setting']
                                                 else
                                                 self.__passenger_temp_setting)
            self.__inside_temp = (data['inside_temp'] if data['inside_temp']
                                  else self.__inside_temp)
            self.__outside_temp = (data['outside_temp'] if data['outside_temp']
                                   else self.__outside_temp)
            self.__fan_status = data['fan_status']


Instruction:
Write a Python 3 function that can
set both the driver and passenger temperature to temp.

Response:
def set_temperature(self, temp):
        """Set both the driver and passenger temperature to temp."""
        temp = round(temp, 1)
        self.__manual_update_time = time.time()
        data = self._controller.command(self._id, 'set_temps',
                                        {"driver_temp": temp,
                                         "passenger_temp": temp},
                                        wake_if_asleep=True)
        if data['response']['result']:
            self.__driver_temp_setting = temp
            self.__passenger_temp_setting = temp


Instruction:
Implement a function in Python 3 to
enable or disable the HVAC.

Response:
def set_status(self, enabled):
        """Enable or disable the HVAC."""
        self.__manual_update_time = time.time()
        if enabled:
            data = self._controller.command(self._id,
                                            'auto_conditioning_start',
                                            wake_if_asleep=True)
            if data['response']['result']:
                self.__is_auto_conditioning_on = True
                self.__is_climate_on = True
        else:
            data = self._controller.command(self._id,
                                            'auto_conditioning_stop',
                                            wake_if_asleep=True)
            if data['response']['result']:
                self.__is_auto_conditioning_on = False
                self.__is_climate_on = False
        self.update()


Instruction:
Can you implement a function in Python 3 that
updates the charging state of the Tesla Vehicle.

Response:
def update(self):
        """Update the charging state of the Tesla Vehicle."""
        self._controller.update(self._id, wake_if_asleep=False)
        data = self._controller.get_charging_params(self._id)
        if data and (time.time() - self.__manual_update_time > 60):
            if data['charging_state'] != "Charging":
                self.__charger_state = False
            else:
                self.__charger_state = True


Instruction:
Explain what the following Python 3 code does
def start_charge(self):
        if not self.__charger_state:
            data = self._controller.command(self._id, 'charge_start',
                                            wake_if_asleep=True)
            if data and data['response']['result']:
                self.__charger_state = True
            self.__manual_update_time = time.time()

Response: Start charging the Tesla Vehicle.


Instruction:
Create a Python 3 function for
stopping charging the Tesla Vehicle.

Response:
def stop_charge(self):
        """Stop charging the Tesla Vehicle."""
        if self.__charger_state:
            data = self._controller.command(self._id, 'charge_stop',
                                            wake_if_asleep=True)
            if data and data['response']['result']:
                self.__charger_state = False
            self.__manual_update_time = time.time()


Instruction:
Implement a Python 3 function for
updating the status of the range setting.

Response:
def update(self):
        """Update the status of the range setting."""
        self._controller.update(self._id, wake_if_asleep=False)
        data = self._controller.get_charging_params(self._id)
        if data and (time.time() - self.__manual_update_time > 60):
            self.__maxrange_state = data['charge_to_max_range']


Instruction:
Can you generate the documentation for the following Python 3 function
def set_max(self):
        if not self.__maxrange_state:
            data = self._controller.command(self._id, 'charge_max_range',
                                            wake_if_asleep=True)
            if data['response']['result']:
                self.__maxrange_state = True
            self.__manual_update_time = time.time()

Response: Set the charger to max range for trips.


Instruction:
How would you explain what the following Python 3 function does
def set_standard(self):
        if self.__maxrange_state:
            data = self._controller.command(self._id, 'charge_standard',
                                            wake_if_asleep=True)
            if data and data['response']['result']:
                self.__maxrange_state = False
            self.__manual_update_time = time.time()

Response: Set the charger to standard range for daily commute.


Instruction:
How would you code a function in Python 3 to
unlock the doors and extend handles where applicable.

Response:
def unlock(self):
        """Unlock the doors and extend handles where applicable."""
        if self.__lock_state:
            data = self._controller.command(self._id, 'door_unlock',
                                            wake_if_asleep=True)
            if data['response']['result']:
                self.__lock_state = False
            self.__manual_update_time = time.time()


Instruction:
Can you write a function in Python 3 where it
closes the charger door.

Response:
def lock(self):
        """Close the charger door."""
        if not self.__lock_state:
            data = self._controller.command(self._id, 'charge_port_door_close',
                                            wake_if_asleep=True)
            if data['response']['result']:
                self.__lock_state = True
            self.__manual_update_time = time.time()


Instruction:
Can you create a Python 3 function that
wraps a API f so it will attempt to wake the vehicle if asleep. The command f is run once if the vehicle_id was last reported online. Assuming f returns None and wake_if_asleep is True, 5 attempts will be made to wake the vehicle to reissue the command. In addition, if there is a `could_not_wake_buses` error, it will retry the command Args: inst (Controller): The instance of a controller vehicle_id (string): The vehicle to attempt to wake. TODO: This currently requires a vehicle_id, but update() does not; This should also be updated to allow that case wake_if_asleep (bool): Keyword arg to force a vehicle awake. Must be set in the wrapped function f Throws: RetryLimitError

Response:
def wake_up(func):
        #  pylint: disable=no-self-argument
        #  issue is use of wraps on classmethods which should be replaced:
        #  https://hynek.me/articles/decorators/
        """Wrap a API f so it will attempt to wake the vehicle if asleep.

        The command f is run once if the vehicle_id was last reported
        online. Assuming f returns None and wake_if_asleep is True, 5 attempts
        will be made to wake the vehicle to reissue the command. In addition,
        if there is a `could_not_wake_buses` error, it will retry the command

        Args:
        inst (Controller): The instance of a controller
        vehicle_id (string): The vehicle to attempt to wake.
        TODO: This currently requires a vehicle_id, but update() does not; This
              should also be updated to allow that case
        wake_if_asleep (bool): Keyword arg to force a vehicle awake. Must be
                               set in the wrapped function f
        Throws:
        RetryLimitError
        """
        @wraps(func)
        def wrapped(*args, **kwargs):
            # pylint: disable=too-many-branches,protected-access, not-callable
            def valid_result(result):
                """Check if TeslaAPI result succesful.

                Parameters
                ----------
                result : tesla API result
                    This is the result of a Tesla Rest API call.

                Returns
                -------
                bool
                  Tesla API failure can be checked in a dict with a bool in
                  ['response']['result'], a bool, or None or
                  ['response']['reason'] == 'could_not_wake_buses'
                  Returns true when a failure state not detected.

                """
                try:
                    return (result is not None and result is not False and
                            (result is True or
                             (isinstance(result, dict) and
                              isinstance(result['response'], dict) and
                              ('result' in result['response'] and
                               result['response']['result'] is True) or
                              ('reason' in result['response'] and
                               result['response']['reason'] !=
                               'could_not_wake_buses') or
                              ('result' not in result['response']))))
                except TypeError as exception:
                    _LOGGER.error("Result: %s, %s", result, exception)
            retries = 0
            sleep_delay = 2
            inst = args[0]
            vehicle_id = args[1]
            result = None
            if (vehicle_id is not None and vehicle_id in inst.car_online and
                    inst.car_online[vehicle_id]):
                try:
                    result = func(*args, **kwargs)
                except TeslaException:
                    pass
            if valid_result(result):
                return result
            _LOGGER.debug("wake_up needed for %s -> %s \n"
                          "Info: args:%s, kwargs:%s, "
                          "vehicle_id:%s, car_online:%s",
                          func.__name__,  # pylint: disable=no-member
                          result, args, kwargs, vehicle_id,
                          inst.car_online)
            inst.car_online[vehicle_id] = False
            while ('wake_if_asleep' in kwargs and kwargs['wake_if_asleep']
                   and
                   # Check online state
                   (vehicle_id is None or
                    (vehicle_id is not None and
                     vehicle_id in inst.car_online and
                     not inst.car_online[vehicle_id]))):
                result = inst._wake_up(vehicle_id)
                _LOGGER.debug("%s(%s): Wake Attempt(%s): %s",
                              func.__name__,  # pylint: disable=no-member,
                              vehicle_id,
                              retries, result)
                if not result:
                    if retries < 5:
                        time.sleep(sleep_delay**(retries+2))
                        retries += 1
                        continue
                    else:
                        inst.car_online[vehicle_id] = False
                        raise RetryLimitError
                else:
                    break
            # try function five more times
            retries = 0
            while True:
                try:
                    result = func(*args, **kwargs)
                    _LOGGER.debug("%s(%s): Retry Attempt(%s): %s",
                                  func.__name__,  # pylint: disable=no-member,
                                  vehicle_id,
                                  retries, result)
                except TeslaException:
                    pass
                finally:
                    retries += 1
                time.sleep(sleep_delay**(retries+1))
                if valid_result(result):
                    return result
                if retries >= 5:
                    raise RetryLimitError
        return wrapped


Instruction:
Can you create a Python 3 function that
sends a command to the vehicle_id.

Response:
def post(self, vehicle_id, command, data=None, wake_if_asleep=True):
        #  pylint: disable=unused-argument
        """Send post command to the vehicle_id.

        This is a wrapped function by wake_up.

        Parameters
        ----------
        vehicle_id : string
            Identifier for the car on the owner-api endpoint. Confusingly it
            is not the vehicle_id field for identifying the car across
            different endpoints.
            https://tesla-api.timdorr.com/api-basics/vehicles#vehicle_id-vs-id
        command : string
            Tesla API command. https://tesla-api.timdorr.com/vehicle/commands
        data : dict
            Optional parameters.
        wake_if_asleep : bool
            Function for wake_up decorator indicating whether a failed response
            should wake up the vehicle or retry.

        Returns
        -------
        dict
            Tesla json object.

        """
        data = data or {}
        return self.__connection.post('vehicles/%i/%s' %
                                      (vehicle_id, command), data)


Instruction:
Can you generate the documentation for the following Python 3 function
def get(self, vehicle_id, command, wake_if_asleep=False):
        #  pylint: disable=unused-argument
        """Send get command to the vehicle_id.

        This is a wrapped function by wake_up.

        Parameters
        ----------
        vehicle_id : string
            Identifier for the car on the owner-api endpoint. Confusingly it
            is not the vehicle_id field for identifying the car across
            different endpoints.
            https://tesla-api.timdorr.com/api-basics/vehicles#vehicle_id-vs-id
        command : string
            Tesla API command. https://tesla-api.timdorr.com/vehicle/commands
        wake_if_asleep : bool
            Function for wake_up decorator indicating whether a failed response
            should wake up the vehicle or retry.

        Returns
        -------
        dict
            Tesla json object.

        """
        return self.__connection.get('vehicles/%i/%s' % (vehicle_id, command))

Response: Send get command to the vehicle_id.