hyb_eval

Read one or more ‘.hyb’ format files and evaluate the contained hybrid sequences.

Evaluation Types:

type

Assigns types to each segment within hyb records

mirna

Assigns which segments are a miRNA based on segment types.

This utility reads in one or more files in hyb-format (see the hybkit Hyb File Specification) and evaluates hybrid record properties.

type Evaluation:
The ‘type’ evaluation utilizes the hybkit.HybRecord.eval_types() method to assign the record flags: seg1_type and seg2_type
Example system calls:
$ hyb_eval -t type -i my_file_1.hyb

$ hyb_eval -t type -i my_file_1.hyb \
           --type_method string_match \
           --type_parameters my_parameters_file.csv \
           --allow_unknown_seg_types
mirna Evaluation:
The ‘mirna’ evaluation uses the hybkit.HybRecord.eval_mirna() method to identify properties relating to mirna within the hybrids, including mirna presence and positions. This evaluation requires the seg_type flags to be filled, either by a type evaluation, or by parsing the read using the --hybformat_ref True option with a hyb-format reference. The mirna_seg flag is then set for each record, indicating the presence and position of any miRNA within the hybrid.
Example system calls:
$ hyb_eval -t mirna -i my_file_1.hyb

$ hyb_eval -t mirna -i my_file_1.hyb \
           --mirna_types miRNA kshv-miRNA

This can also be combined with the type evaluation, as such:

$ hyb_eval -t type mirna -i my_file_1.hyb

–type_method string_match –type_parameters my_parameters_file.csv –allow_unknown_seg_types –mirna_types miRNA kshv-miRNA

Output File Naming:

Output files can be named in two fashions: via automatic name generation, or by providing specific out file names.

Automatic Name Generation:

For output name generation, the default respective naming scheme is used:

hyb_script -i PATH_TO/MY_FILE_1.HYB [...]
    -->  OUT_DIR/MY_FILE_1_ADDSUFFIX.HYB

This output file path can be modified with the arguments {–out_dir, –out_suffix} described below.

The output directory defaults to the current working directory ($PWD), and can be modified with the --out_dir <dir> argument. Note: The provided directory must exist, or an error will be raised. For Example:

hyb_script -i PATH_TO/MY_FILE_1.HYB [...] --out_dir MY_OUT_DIR
    -->  MY_OUT_DIR/MY_FILE_1_ADDSUFFIX.HYB

The suffix used for output files is based on the primary actions of the script. It can be specified using --out_suffix <suffix>. This can optionally include the “.hyb” final suffix. for Example:

hyb_script -i PATH_TO/MY_FILE_1.HYB [...] --out_suffix MY_SUFFIX
    -->  OUT_DIR/MY_FILE_1_MY_SUFFIX.HYB
#OR
hyb_script -i PATH_TO/MY_FILE_1.HYB [...] --out_suffix MY_SUFFIX.HYB
    -->  OUT_DIR/MY_FILE_1_MY_SUFFIX.HYB
Specific Output Names:

Alternatively, specific file names can be provided via the -o/–out_hyb argument, ensuring that the same number of input and output files are provided. This argument takes precedence over all automatic output file naming options (–out_dir, –out_suffix), which are ignored if -o/–out_hyb is provided. For Example:

hyb_script [...] --out_hyb MY_OUT_DIR/OUT_FILE_1.HYB MY_OUT_DIR/OUT_FILE_2.HYB
    -->  MY_OUT_DIR/OUT_FILE_1.hyb
    -->  MY_OUT_DIR/OUT_FILE_2.hyb

Note: The directory provided with output file paths (MY_OUT_DIR above) must exist, otherwise an error will be raised.

usage: hyb_analysis [-h] -i PATH_TO/MY_FILE.HYB [PATH_TO/MY_FILE.HYB ...]
                    [-o PATH_TO/OUT_FILE.HYB [PATH_TO/OUT_FILE.HYB ...]]
                    [-d OUT_DIR] [-u OUT_SUFFIX]
                    [-t {type,mirna} [{type,mirna} ...]]
                    [--type_method {hybformat,string_match,id_map}]
                    [--type_params_file PATH_TO/PARAMATERS_FILE]
                    [--set_dataset] [-v | -s]
                    [--mirna_types MIRNA_TYPES [MIRNA_TYPES ...]]
                    [--custom_flags CUSTOM_FLAGS [CUSTOM_FLAGS ...]]
                    [--hyb_placeholder HYB_PLACEHOLDER]
                    [--reorder_flags {True,False}]
                    [--allow_undefined_flags [{True,False}]]
                    [--allow_unknown_seg_types [{True,False}]]
                    [--check_complete_seg_types [{True,False}]]
                    [--hybformat_id [{True,False}]]
                    [--hybformat_ref [{True,False}]]

Named Arguments

-i, --in_hyb

REQUIRED path to one or more hyb-format files with a “.hyb” suffix for use in the evaluation.

-o, --out_hyb

Optional path to one or more hyb-format file for output (should include a “.hyb” suffix). If not provided, the output for input file “PATH_TO/MY_FILE.HYB” will be used as a template for the output “OUT_DIR/MY_FILE_OUT.HYB”.

-d, --out_dir

Path to directory for output of evaluation files. Defaults to the current working directory.

Default: $PWD

-u, --out_suffix

Suffix to add to the name of output files, before any file- or analysis-specific suffixes. The file-type appropriate suffix will be added automatically.

Default: “_evaluated”

-t, --eval_types

Possible choices: type, mirna

Types of evaluations to perform on input hyb file. (Note: evaluations can be combined, such as “–eval_types type mirna”)

Default: [‘type’]

--set_dataset

Set “dataset” flag to value of the input file name.

Default: False

-v, --verbose

Print verbose output during run.

Default: False

-s, --silent

Print no output during run.

Default: False

type Analysis Options

--type_method

Possible choices: hybformat, string_match, id_map

Segment-type finding method to use for type evaluation. For a description of the different methods, see the HybRecord documentation for the eval_types method.

Default: “hyb”

--type_params_file

Segment-type finding paramaters file to use for type evaluation with some type finding methods: {string_match, id_map}. For a description of the different methods, see the HybRecord documentation for the find_seg_types method.

Hyb Record Settings

--mirna_types

“seg_type” fields identifying a miRNA

Default: [‘miRNA’, ‘microRNA’]

--custom_flags

Custom flags to allow in addition to those specified in the hybkit specification.

Default: []

--hyb_placeholder

placeholder character/string for missing data in hyb files.

Default: “.”

--reorder_flags

Possible choices: True, False

Re-order flags to the hybkit-specificiation order when writing hyb records.

Default: True

--allow_undefined_flags

Possible choices: True, False

Allow use of flags not definied in the hybkit-specificiation order when reading and writing hyb records. As the preferred alternative to using this setting, the –custom_flags arguement can be be used to supply custom allowed flags.

Default: False

--allow_unknown_seg_types

Possible choices: True, False

Allow unknown segment types when assigning segment types.

Default: False

--check_complete_seg_types

Possible choices: True, False

Check every segment possibility when assigning segment types, rather than breaking after the first match is found. If True, finding segment types is slower but better at catching errors.

Default: False

Hyb File Settings

--hybformat_id

Possible choices: True, False

The Hyb Software Package places further information in the “id” field of the hybrid record that can be used to infer the number of contained read counts. When set to True, the identifiers will be parsed as: “<read_id>_<read_count>”

Default: False

--hybformat_ref

Possible choices: True, False

The Hyb Software Package uses a reference database with identifiers that contain sequence type and other sequence information. When set to True, all hyb file identifiers will be parsed as: “<gene_id>_<transcript_id>_<gene_name>_<seg_type>”

Default: False