# gcatlib reference

Gene and Chromosome Analysis Toolkit (gcat) is a C++ library for most
common tasks associated with genomic data files such as for parsing
FASTX, SAM/BAM, and GTF files. gcat is conceptually identical to 
[`pysam`](https://pysam.readthedocs.io/en/latest/api.html) and 
[`HTseq`](https://htseq.readthedocs.io/en/latest/), and 
borrows ideas from them.

The documentation for gcatlib will be made available soon. 

## Installation


##### Preparation
`gcat` is dependent on `HTSlib`. `HTSlib` can be downloaded from
[here](https://www.htslib.org/download/) and can be installed by
following the procedure under 'Basic Installation' described
[here](https://github.com/samtools/htslib/blob/develop/INSTALL)

`gcatlib` can be downloaded [here](
https://github.com/rishvanth-kp/gcatlib/releases)

Untar the source files using:
```
tar -xf gcatlib-x.y.z.tar.gz
```

Create a build directory with:
```
cd gcatlib-x.y.z
mkdir build 
cd build
```

##### Configure
`gcatlib` is installed using the `autotools` build system.  The first
step is to run a configuration script to generate the required
Makefiles. The parameters to `configure` will vary based on where the
dependent libraries are installed, and where we would like `gcatlib`
to be installed. 


1) The most likely scenario, where `HTSlib` is not in the the standard
system path (typically `/usr/bin` and `/usr/lib`), and to install
`gcatlib` in a non-standard path:

```
../configure --prefix=path_to_install_gcatlib \ 
  CPPFLAGS='-I/path_to_htslib/include' \
  LDFLAGS='-L/path_to_htslib/lib'
```

2) If `HTSlib` is installed in the standard system path (typically
`/usr/bin` and `/usr/lib`), and if we would like `gcatlib` to be
installed in the standard system path, use the following: 

```
../configure
```


3) To install gcatlib in a non-standard directory, and if `HTSlib` is in the 
standard system path use:

```
../configure --prefix=path_to_install_gcatlib
```

4) If `HTSlib` is installed in a non-standard path and to install
gcatlib in the standard system path, the `configure` script should be
executed with:

```
../configure CPPFLAGS='-I/path_to_htslib/include' \ 
  LDFLAGS='-L/path_to_htslib/lib'
```


Of note, if you have cloned the Git repo, it does not include the
`configure` script. This can be generated by executing:
```
autoreconf -i
```
After which the configuration can proceed as usual.

##### Build

The configuration is now complete and the build system is ready to
compile all the programs with:
```
make [-j threads]
```
This will generate the libraries into the `build` directory.


##### Install 

Finally, install gcatlib with:
```
make install
```
This will copy all the header files into `installation_path/include` and
the library files into `installation_path/lib`.



## Copyright and License Information
Copyright (C) 2025 Rishvanth Prabakar

Authors: Rish Prabakar

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License along
with this program; if not, write to the Free Software Foundation, Inc.,
51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.


## API documentation
```{toctree}
:maxdepth: 1

api/readers
api/stepvector
api/metagene
```

## Performance
```{toctree}
:maxdepth: 1

performance
```