CONTRIBUTING.rst

Writing your own commands

Maybe you will be interested in helping us in the future by sharing your own commands. We provide an example below of the development of a very basic command that prints a GTF file.

Just do the following things to declare a new command named 'print_gtf':

• Write a script using the template provided below. This script can be run as a stand-alone script or as a gtftk plugin.
• Add this script to the gtftk/plugins or ~/.gtftk/plugins/ directories.
• Call gtftk -u to update the plugin list. A new command should be available upon gtftk -h.
• You can propose new commands by sending us pull requests.

#!/usr/bin/env python
"""
This is the doc about the command that will appear when gtftk my_command -h
is called...
"""

import sys
import argparse
from pygtftk.cmd_object import CmdObject
from pygtftk.gtf_interface import GTF
from pygtftk import arg_formatter

#-------------------------------------------------------------------------
# NOTES: Just place this file into ~/.gtftk/plugins
# and ask for:
#    gtftk --update-plugins
# gtftk will load the plugin next time it is called.
#-------------------------------------------------------------------------



#-------------------------------------------------------------------------
# Message can be of type "INFO" (default), "WARNING" or "ERROR"
# When using message it will adapt to the user-declared level of
# verbosity (as passed through the -V argument of the CLI).
#-------------------------------------------------------------------------

from pygtftk.utils import message

#-------------------------------------------------------------------------
# Any temporary file created using the make_tmp_file function
# will be deleted upon exit or may be kept into a target directory (see -K
# command-wise argument)
# This command should thus be used to create any temporary file.
#-------------------------------------------------------------------------

from pygtftk.utils import make_tmp_file

#-------------------------------------------------------------------------
# Command information
#-------------------------------------------------------------------------

__notes__ = """
-- A note that will appear when 'gtftk my_command -h' will be called.
-- Another note. If you want to refer to long form arguments use '\'. e.g -\-distance.
"""


#-------------------------------------------------------------------------
# First define the function/command arguments.
# Note that the syntax is the same that would be used for a regular program
# implementing an argument parser.
# Make use as possible of argparse.FileType and more complexes types as
# found in gtftk.arg_formatter.
#-------------------------------------------------------------------------

def make_parser():
   parser = argparse.ArgumentParser(add_help=True)

   parser_grp = parser.add_argument_group('Arguments')

   parser_grp.add_argument('-i', '--inputfile',
                           help="Path to the GTF file. Default to STDIN",
                           default=sys.stdin,
                           metavar="GTF",
                           type=arg_formatter.FormattedFile(mode='r', file_ext=('gtf', 'gtf.gz')))


   parser_grp.add_argument('-o', '--outputfile',
                           help="Output file.",
                           default=sys.stdout,
                           metavar="GTF",
                           type=arg_formatter.FormattedFile(mode='w', file_ext=('gtf')))

    return parser

#-------------------------------------------------------------------------
# Now we declare a main function, as would be done
# for a regular program
#-------------------------------------------------------------------------


# NB: The verbosity, tmp_dir=None and logger_file are mandatory arguments

def print_gtf(inputfile=None,
              outputfile=None,
              tmp_dir=None,
              logger_file=None,
              verbosity=0):
    """This function will only print a GTF..."""

    message("Reading GTF")
    gtf = GTF(inputfile)
    gtf.write(outputfile)

#-------------------------------------------------------------------------
# Now we check if the python interpreter is running this module
# as the main program or whether it is called by the plugin manager.
#-------------------------------------------------------------------------

def main():
    """The main function."""
    args = make_parser().parse_args()
    args = dict(args.__dict__)
    print_gtf(**args)

if __name__ == '__main__':
    main()
else:

    # Just declare a new command object
    # That will call the command manager.
    # With the user-passed arguments.
    # Available groups are: editing, information, selection, conversion,
    # coordinates, annotation, sequences, coverage,
    # and miscellaneous.

    cmd = CmdObject(name="print_gtf",
                    message="Print a GTF",
                    parser=make_parser(),
                    fun=os.path.abspath(__file__),
                    group="miscellaneous",
                    desc=__doc__,
                    notes=__notes__)