# BAM Report
This tool was created to support research efforts using [this workflow](https://code.cs.earlham.edu/hts/hts-workflow) and to provide a quick and easy way to view and interpret the contents of a BAM file created with that workflow. 

The software here depends on having PSQL databases set up for lookup efficiency. The software to create those PSQL databases can be found [here](https://code.cs.earlham.edu/hts/ncbi2psql).



## Examples
```
python3 bamreport.py \
  -i /path/to/input.bam \
  -o /path/to/output.csv \
  -t genus
```

## Options
- `--input` `-i`: (Required) File path for input BAM files to be processed.
- `--output` `-o`: (Required) File path for output CSV file.
- `--tax_level` `-t`: (Required) Target level of taxonomic specificity. Accepts values like "genus", "family", "species".
- `--damage` `-d`: (Optional, default False) Setting "True" will include damage columns, looks for *DS:Z* flag in bam files which is created by PMDtools.
- `--primary` `-p`: (Optional, default False) Setting "True" will result in a CSV that *only* includes primary alignments for each read, and no secondary or supplimentary alignments.

## Analysis and Tags
`as` (Alignment Score) - The total score calculated by the aligner based on its scoring matrix. It awards points for matches and subtracts points for mismatches, insertions, or deletions (indels). Includes rows with max, min, avg, and std-dev.

`nm` (Edit Distance) - The total number of nucleotide changes required to make the read match the reference perfectly. This includes mismatches, insertions, and deletions. Includes rows with max, min, avg, and std-dev.

`xm` (Number of Mismatches) - Specifically counts the number of mismatches (snips/substitutions) between the read and the reference. It ignores indels. Includes rows with max, min, avg, and std-dev.

`ds` (Damage Score) - Damage score as annotated by software like PMDTools. Includes rows with max, min, avg, and std-dev.

## Other scripts
- `gbif_annotate.py` - Add occurance column to a CSV, uses GBIF to query information from NCBI taxids. Includes citizen science reports and single occurances of a species shouldn't be taken as peer-reviewed fact without furhter research. Can be used in a loop to annotate all CSVs for a project:
  ```sh
  for x in /path/to/all/files/*.csv; do
      python annotate_location.py -c IS -e [EMAIL] $x;
  done;
  ```
- `combine_features.py` - Combine/summarize a folder of CSVs (output from bamreport) into a matrix of alignment counts for each sample/input ID.
  ```sh
  python3 combine_features.py  -i /path/to/input/dir -o feature_output.csv
  ```
- `comfine_taxonomy.py` - Combine/summarize a folder of CSVs (output from bamreport) into a simple taxonomy file. 
  ```sh
  python3 comfine_taxonomy.py  -i /path/to/input/dir -o tax_output.csv
  ```

## ENV File for NCBI2PSQL databases
```
DB_NAME=<DATABASE NAME>
DB_USER=<DATABASE USER>
DB_PASS=<DATABASE PASSWORD>
```

## Some older notes: 
- Add script to annotate geographic area
- Added columns for other metrics: AS, NM, XM.
- Added DS columns
- Creates a CSV report from a BAM file, one row per unique taxon (at target level -t).
- This one is modified to include the full taxonomy and damage score statistics and buckets.
- Output will include the following columns:
  - Domain,Kingdom,Phylum,Class,Order,Family,Genus,taxid_at_target_level,read_count,read_percent,sample_id,ds_avg,DS_1to2,DS_3to4,DS_5to9,DS_10plus,sample_id
