Quickstart guide
=====================

Installation
------------

This library requires Python 3.10+ and can be installed with pip:

.. code:: shell

   pip install proffer

Basic Usage
-----------

After installation, you can run the ``proffer`` CLI tool:

.. code:: shell

   proffer data/percolator.txt --format tsv

You can also load results directly from any URI supported by
`fsspec <https://filesystem-spec.readthedocs.io/en/latest/>`_:

.. code:: shell

   # HTTP(S)
   proffer https://github.com/seerbio/proffer/raw/refs/heads/main/data/percolator.txt --format tsv

   # S3
   pip install proffer[s3]  # ensure libraries for S3 support are installed
   proffer s3://bucket/key/results.parquet --format parquet

Basic support is included for thresholding peptide identifications
before inference:

.. code:: shell

   proffer data/percolator.txt --format tsv --qvalue-threshold 0.01

By default output is written in JSON format to stdout. Alternatively,
the ``-o`` flag can be used to write results to Parquet:

.. code:: shell

   proffer data/percolator.txt --output proffer-results.parquet

It is possible to configure the column names used, as well as the
approach used to pick protein groups. To learn more about the available
options you can run:

.. code:: shell

   proffer --help

Python usage
------------

To use Proffer in your Python code, call :py:func:`proffer.infer() <proffer.infer.infer>` with a Polars
DataFrame:

.. code:: python

   import proffer

   result_frame = proffer.infer(polars_frame)

It is possible to configure the column names used, as well as the
approach used to pick protein groups. To learn more about the available
options see :py:func:`proffer.infer() <proffer.infer.infer>` or run:

.. code:: shell

   python -c 'import proffer; help(proffer.infer)'

Usage with Fulcrum Pipeline
---------------------------

Utilities for working with Spark-based datasets can be found in
:py:mod:`proffer.spark`. These use interfaces from
`wheely-mammoth <https://github.com/seerbio/wheely-mammoth>`_
(compatible with `Fulcrum Pipeline™ <https://github.com/seerbio/fulcrum>`_) to
efficiently read peptide and protein information and compute inference.

For typical use cases, it will be easiest to employ a pre-built Fulcrum
workflow that uses Proffer for inference, rather than call these
utilities directly.

By default, installing Proffer will not install Spark dependencies; to
use Proffer in an environment where these are not already installed,
run:

.. code:: shell

   pip install 'proffer[spark]'