Package: pygustus
PygustusA python wrapper for the gene prediction program AUGUSTUS.RequirementsInstallationUsageExamplesRequirementsTo use Pygustus, an installed or built AUGUSTUS with minimum program version 3.3.2 is required. Using Ubuntu, AUGUSTUS can be installed as follows.sudo apt install augustus augustus-data augustus-docMore information can be found on theAUGUSTUS GitHub page.To run Pygustus properly it is necessary that the AUGUSTUS environment variableAUGUSTUS_CONFIG_PATHis set correctly and points to the configuration directory.If AUGUSTUS was built from source and no installation was done (so the commandaugustusis not executable), then the path to the executable can be set as described in theconfigurationsection.For Pygustus Python version 3.6 or higher is required.The following examples assume that Python 3 is the default on the executing system. To ensure the usage of Python 3, the use of a virtual environment is recommended. A virtual environment can be created withvenv.InstallationPygustus is in alpha development status.Currently it is not recommended for productive use.Pygustus can be installed from PyPi as follows.pip install pygustusBuilding Pygustus from source:warning: Pygustus currently only works with Augustus from git, not with Augustus from package managers or third parties. The crucial commit was performed on Feb 28 2023.As an alternative to installing Pygustus from PyPi, Pygustus can also be built from source as follows. After cloning the repository from GitHub,git clone git@github.com:Gaius-Augustus/pygustus.gitrequired dependencies need to be installed.pip install numba property-manager pysais
# sometimes required: pip install --force-reinstall -v "numpy==1.23"
# sometimes required: pip install --force-reinstall -v "numexpr==2.6.2"
pip install -r requirements.txt
# can be skipped for just installing the package: pip install -r requirements-dev.txtAfter that Pygustus can be built and installed as follows.python setup.py sdist bdist_wheel
pip install dist/pygustus-<VERSION>.tar.gzFor the execution of the testspytestis used. Example usage:pytest -m ghactions tests/The test cases marked withghactionsare those that are not too expensive in terms of runtime.UsagePygustuts supports the training and prediction of AUGUSTUS. The prediction can be executed either in a single thread or in parallel. In multithreaded execution, the input file is split into smaller pieces and AUGUSTUS is executed in parallel on partial inputs. Finally, the partial results are joined together.As values of the parameters for all Pygustus programs only the Python types are permissible.TrainingTo train AUGUSTUS, the etraining program was adopted in Pygustus. More information about the program can be foundhere. The usage in Pygustus is as follows.from pygustus import etraining

etraining.train('path/to/trainfilename.gb',  species='SPECIES')The species to be trained must be present in the config folder of AUGUSTUS (see also AUGUSTUS_CONFIG_PATH). To create a new species, the Perl scriptnew_species.plfrom the script folder of AUGUSTUS can be used.If the path to the etraining executable is to be specified temporarily, the Pygustus parameterpath_to_binary=path/to/etrainingcan be used.PredictionTo run a prediction AUGUSTUS can be executed on the input file as usual or the input file can be split and AUGUSTUS is run on input parts in parallel. For the second variant the Pygustus parameterjobs=nmust be set withn > 1.Default (Single Thread)If the prediction is executed withjobs=1(default, may be ommitted), AUGUSTUS is executed on the input file exactly as if one would start AUGUSTUS from the console. Usage example:from pygustus import augustus

augustus.predict('path/to/input/file', species='human',
                    UTR=True, softmasking=False)To redirect the output to a file the AUGUSTUS parametersoutfileanderrfilecan be used. Application example for the output of the prediction and the possible errors that occurredaugustus.predict('path/to/input/file', species='human',
                UTR=True, softmasking=False
                outfile='out.gff', errfile='out.err')If the path to the AUGUSTUS executable is to be specified temporarily, the Pygustus parameterpath_to_binary=path/to/augustuscan be used.MultithreadedIf the Pygustus parameterjobs=nis set withn > 1, then the input file is split into several small files and Augustus is run in parallel for each file with the given parameters. After AUGUSTUS has been executed on all parts, the partial results are combined to the final result. If the parameteroutfileis set, the result will be saved in the file given there. Otherwise, the result will be saved in the fileaugustus.gff(default). A usage example is shown below.from pygustus import augustus

augustus.predict('path/to/input/file', [augustus_parameters],
                    [pygustus_parameters], jobs=n)All parameters permitted for AUGUSTUS can be used as augustus_parameters. The following pygustus_parameters are additionally available.ParameterDefault ValueDescriptionjobs (int)1Ifjobs=nwithn > 1is set, AUGUSTUS is executed in parallel on sequence segments or split input files usingnjobs. After the execution of all jobs, the output files are merged.chunksize (int)2500000Ifchunksize=nwithn > 0is set andjobs > 1, each AUGUSTUS instance is executed on sequence segments of the maximum sizen.overlap (int)500000Ifoverlap=nwithn > 1is set andjobs > 1, each AUGUSTUS instance is executed on sequence segments of sizechunksizeand the segments overlap byn.partitionHints (bool)FalseIf this option is set to True, a hints file is given andjobs > 1, then the hints file is split into appropriate pieces for the respective AUGUSTUS jobs.minSplitSize (int)1000000The input fasta file is spilt to at leastminSplitSize=nbase pairs. Setn=0to split the input in single sequence files.partitionLargeSequences (bool)FalseParallelize large sequences by automatically setting the AUGUSTUS parameterspredictionStartandpredictionEndbased on the given values forchunksizeandoverlap.maxSeqSize (int)3500000The maximum length of a sequence from which the sequence is started to be partitioned. To turn on the paritioningpartitionLargeSequences=Truemust be setdebugOutputDir (string)NoneIf the directory is specified, all generated files, i.e. the split of the input file and intermediate results, as well as the generated AUGUSTUS command lines are stored there. This option works only for the parallelization, i. e.jobs > 1is set.path_to_bin (string)NoneSets the path to the desired executable version of AUGUSTUS whenaugustus.predict()is called or etraining whenetraining.train()is called. The path is not saved for further executions.To redirect the output to a file the AUGUSTUS parametersoutfileanderrfilecan be used as for the default case.ConfigurationThe paths to theaugustusandetrainingbinaries be configured. This path is only used if the Pygustus parameterpath_to_binis not specified. This configuration is saved until the next change. The configuration is identical forpygustus.etrainingandpygustus.augustus, so that the following example is restricted topygustus.augustus.Read the configured pathTo get the the currently configured path to the executable of AUGUSTUS you can proceed as follows.from pygustus import augustus

augustus.config_get_bin()Update the path to the binaryTo update the currently configured path to the executable of AUGUSTUS you can proceed as follows.augustus.config_set_bin(path/to/augustus)Set the default binaryTo set the default binary you can proceed as follows.augustus.config_set_default_bin()This method sets the configured path to the AUGUSTUS executable toaugustus. This should exist if AUGUSTUS is properly installed on the system.As mentioned earlier, the configured path can be overridden by specifying the Pygustus parameterpath_to_binfor the current prediction with augustus or the current training with etraining.HelpTo have easy access to the AUGUSTUS and Pygustus help system, the following methods are available.MethodDescriptionhelp()Shows usage information about the Pygustus wrapper and its parameters.show_aug_help()Shows the help output of AUGUSTUS, equivalent to the AUGUSTUS call with the parameter--help.show_aug_paramlist()Shows all possible parameter names of AUGUSTUS, equivalent to the AUGUSTUS call with the parameter--paramlist.show_species_info()Shows species information of AUGUSTUS, equivalent to the AUGUSTUS call with the parameter--species=help.Usage examplefrom pygustus import augustus

augustus.help()ExamplesThe use of Pygustus is also demonstrated with an executable Python script and a Jupyter notebook. The script assumes that Pygustus and AUGUSTUS are installed as described above.Executable exampleThe following command lines install required dependencies, download the script and execute it. The script creates a folder structure in the working directory and downloads required data. After that different AUGUSTUS prediction examples are executed with Pygtustus.pip install wget
wget https://raw.githubusercontent.com/Gaius-Augustus/pygustus/main/examples/aug_run_examples.py
chmod +x aug_run_examples.py
./aug_run_examples.pyAfter execution, the debug folder contains the generated AUGUSTUS command lines as well as the split input files for parallel execution.Jupyter notebookHow the output of the examples should look like can also be taken from a Jupyternotebook.