API functions

BuddySuite Module Section

This is where most of the data processing logic should live. The first parameter passed into every function is a buddy object, and care should be taken to limit the number of subsequent parameters to the fewest possible. If more arguments are accepted, then check them carefully! The main API section is where things should halt and catch fire if someone tries to pass in bad arguments, so do the necessary checking and raise meaningful exceptions.

Function names should be informative, and variable names within the function should not shadow variable names in the broader scope of the program. Also, please try hard to avoid printing anything to stdout or stderr from within these functions. The goal is to completely encapsulate everything in the main API to maximize flexibility and usability by other functions. Indeed, go ahead and call other BuddySuite API functions in your own function, there's no need to reinvent the wheel.

Function output falls into two categories: 1) A new/modified buddy object, 2) something else. If the output is not a buddy object, choose a data structure that is easy to parse by others. For example, if calculating a numerical property for each sequence in a seqbuddy object DO NOT create a table and return it as a string. A better option is to return a list or dictionary, or even append the new properties to the seqbuddy records directly. Make it clear in the meta data what the output should look like.

Example function

def pull_random_recs(seqbuddy, count=1):
    """
    Return a random set of sequences (without replacement)
    :param seqbuddy: SeqBuddy object
    :param count: The number of random records to pull
    :return: The original SeqBuddy object with only the selected records remaining
    """
    if type(count) != int:
        raise TypeError("count parameter requires an integer as input.")
    
    count = abs(count) if abs(count) <= len(seqbuddy.records) else len(seqbuddy.records)
    random_recs = []
    for i in range(count):
        rand_index = randint(0, len(seqbuddy.records) - 1)
        random_recs.append(seqbuddy.records.pop(rand_index))

    seqbuddy.records = random_recs
    return seqbuddy