spacr.sequencing
================

.. py:module:: spacr.sequencing




Module Contents
---------------

.. py:function:: map_sequences_to_names(csv_file, sequences, rc)

   Map DNA sequences to their names via a lookup CSV of ``sequence,name``.

   Only the CSV sequences are reverse-complemented when ``rc`` is true;
   the input ``sequences`` are matched as given.

   :param csv_file: path to a CSV with ``sequence`` and ``name`` columns.
   :param sequences: DNA sequences to look up.
   :param rc: reverse-complement the CSV sequences before matching.
   :returns: list of names aligned with ``sequences``; ``pd.NA`` for misses.


.. py:function:: save_df_to_hdf5(df, hdf5_file, key='df', comp_type='zlib', comp_level=5)

   Append (or create) ``df`` to a ``table``-format HDF5 dataset.

   :param df: DataFrame to persist.
   :param hdf5_file: destination HDF5 file path.
   :param key: dataset key inside the store. Default ``'df'``.
   :param comp_type: compression library. Default ``'zlib'``.
   :param comp_level: compression level 0-9. Default ``5``.
   :returns: None. Errors are printed instead of raised.


.. py:function:: save_unique_combinations_to_csv(unique_combinations, csv_file)

   Append per-``(rowID, columnID, grna_name)`` counts to a CSV, summing duplicates.

   :param unique_combinations: DataFrame with ``rowID``, ``columnID``, ``grna_name`` and numeric count columns.
   :param csv_file: destination CSV path (created if absent).
   :returns: None. Errors are printed instead of raised.


.. py:function:: save_qc_df_to_csv(qc_df, qc_csv_file)

   Append a QC DataFrame to a CSV, summing element-wise when the file already exists.

   :param qc_df: numeric QC metrics (e.g. missing counts, total reads).
   :param qc_csv_file: destination CSV path.
   :returns: None. Errors are printed instead of raised.


.. py:function:: extract_sequence_and_quality(sequence, quality, start, end)

   Return the ``[start:end]`` slice of a sequence and its paired quality string.

   :param sequence: DNA sequence.
   :param quality: quality string of equal length.
   :param start: inclusive start index.
   :param end: exclusive end index.
   :returns: tuple ``(subsequence, subquality)``.


.. py:function:: create_consensus(seq1, qual1, seq2, qual2)

   Return a per-position consensus of two equal-length reads.

   At each position the higher-quality base is kept; if one call is ``N``
   the other is preferred regardless of quality.

   :param seq1: first DNA sequence.
   :param qual1: quality string for ``seq1``.
   :param seq2: second DNA sequence.
   :param qual2: quality string for ``seq2``.
   :returns: the consensus sequence as a string.


.. py:function:: get_consensus_base(bases)

   Return the higher-quality base from two ``(base, quality)`` pairs, preferring non-``N``.

   :param bases: list of two ``(base, quality)`` tuples.
   :returns: the chosen base as a single-character string.


.. py:function:: reverse_complement(seq)

   Return the reverse complement of a DNA sequence via BioPython.

   :param seq: DNA sequence.
   :returns: reverse-complemented sequence as a string.


.. py:function:: process_chunk(chunk_data)

   Extract and map barcodes from a chunk of single- or paired-end FASTQ reads.

   Anchors on ``target_sequence``, extracts a consensus window, splits it
   with the named-group ``regex``, and maps each barcode to its ID via
   the reference CSVs.

   :param chunk_data: 9-tuple for single-end
       ``(r1_chunk, regex, target_sequence, offset_start, expected_end,
       column_csv, grna_csv, row_csv, fill_na)`` or 10-tuple for paired-end
       ``(r1_chunk, r2_chunk, ...)`` with the same trailing fields.
   :returns: tuple ``(df, unique_combinations, qc_df)`` — the annotated
       reads (``read``, per-barcode sequences and IDs), per-triplet counts,
       and a NaN/total-reads QC row.


.. py:function:: saver_process(save_queue, hdf5_file, save_h5, unique_combinations_csv, qc_csv_file, comp_type, comp_level)

   Background writer that drains ``save_queue`` and persists each item.

   Runs until the sentinel ``"STOP"`` arrives on the queue.

   :param save_queue: multiprocessing queue delivering ``(df, unique_combinations, qc_df)`` tuples.
   :param hdf5_file: HDF5 destination for full annotated reads.
   :param save_h5: enable HDF5 writes of the reads DataFrame.
   :param unique_combinations_csv: destination CSV for aggregated barcode combinations.
   :param qc_csv_file: destination CSV for QC statistics.
   :param comp_type: HDF5 compression library.
   :param comp_level: HDF5 compression level.
   :returns: None.


.. py:function:: paired_read_chunked_processing(r1_file, r2_file, regex, target_sequence, offset_start, expected_end, column_csv, grna_csv, row_csv, save_h5, comp_type, comp_level, hdf5_file, unique_combinations_csv, qc_csv_file, chunk_size=10000, n_jobs=None, test=False, fill_na=False)

   Chunked paired-end FASTQ processing: extract, decode and stream barcodes to disk.

   Reads R1/R2 in ``chunk_size`` blocks, farms them out to
   :func:`process_chunk` workers, and lets :func:`saver_process` write
   HDF5 / CSV outputs concurrently.

   :param r1_file: gzipped R1 FASTQ path.
   :param r2_file: gzipped R2 FASTQ path.
   :param regex: regex with named groups ``rowID``, ``columnID``, ``grna``.
   :param target_sequence: anchor sequence used to locate the barcode region.
   :param offset_start: offset from ``target_sequence`` to begin extraction.
   :param expected_end: length of the extracted consensus region.
   :param column_csv: column-barcode reference CSV.
   :param grna_csv: gRNA-barcode reference CSV.
   :param row_csv: row-barcode reference CSV.
   :param save_h5: persist the full reads DataFrame to HDF5.
   :param comp_type: HDF5 compression library.
   :param comp_level: HDF5 compression level.
   :param hdf5_file: HDF5 output path.
   :param unique_combinations_csv: destination CSV for aggregated combinations.
   :param qc_csv_file: destination CSV for QC statistics.
   :param chunk_size: reads per batch. Default ``10000``.
   :param n_jobs: worker processes; defaults to ``cpu_count() - 3``.
   :param test: process only the first chunk and print a preview.
   :param fill_na: fill unmapped IDs with raw barcode sequences.
   :returns: None.


.. py:function:: single_read_chunked_processing(r1_file, r2_file, regex, target_sequence, offset_start, expected_end, column_csv, grna_csv, row_csv, save_h5, comp_type, comp_level, hdf5_file, unique_combinations_csv, qc_csv_file, chunk_size=10000, n_jobs=None, test=False, fill_na=False)

   Chunked single-end FASTQ processing: extract, decode and stream barcodes to disk.

   :param r1_file: gzipped R1 FASTQ path.
   :param r2_file: unused placeholder kept for interface parity with the paired variant.
   :param regex: regex with named groups ``rowID``, ``columnID``, ``grna``.
   :param target_sequence: anchor sequence used to locate the barcode region.
   :param offset_start: offset from ``target_sequence`` to begin extraction.
   :param expected_end: length of the extracted barcode region.
   :param column_csv: column-barcode reference CSV.
   :param grna_csv: gRNA-barcode reference CSV.
   :param row_csv: row-barcode reference CSV.
   :param save_h5: persist the full reads DataFrame to HDF5.
   :param comp_type: HDF5 compression library.
   :param comp_level: HDF5 compression level.
   :param hdf5_file: HDF5 output path.
   :param unique_combinations_csv: destination CSV for aggregated combinations.
   :param qc_csv_file: destination CSV for QC statistics.
   :param chunk_size: reads per batch. Default ``10000``.
   :param n_jobs: worker processes; defaults to ``cpu_count() - 3``.
   :param test: process only the first chunk and print a preview.
   :param fill_na: fill unmapped IDs with raw barcode sequences.
   :returns: None.


.. py:function:: generate_barecode_mapping(settings=None)

   Discover FASTQ samples and dispatch chunked barcode extraction for each.

   Groups R1/R2 files per sample, then calls
   :func:`paired_read_chunked_processing` or
   :func:`single_read_chunked_processing` depending on ``settings['mode']``,
   writing ``annotated_reads.h5`` (optional), ``unique_combinations.csv``
   and ``qc.csv`` under each sample's output directory.

   :param settings: dict of barcode-mapping settings; see
       ``set_default_generate_barecode_mapping`` for keys (``src``,
       ``mode``, ``single_direction``, ``regex``, ``target_sequence``,
       ``offset_start``, ``expected_end``, ``column_csv``, ``grna_csv``,
       ``row_csv``, ``save_h5``, ``comp_type``, ``comp_level``,
       ``chunk_size``, ``n_jobs``, ``test``, ``fill_na``).
   :returns: None. Writes per-sample HDF5 and CSV outputs to disk.


.. py:function:: barecodes_reverse_complement(csv_file)

   Write a copy of a barcode CSV with the ``sequence`` column reverse-complemented.

   Output is saved as ``<csv_file>_RC.csv`` in the same directory.

   :param csv_file: input CSV path with a ``sequence`` column.
   :returns: None.


.. py:function:: graph_sequencing_stats(settings)

   Pick the fraction cutoff that yields a target mean of unique gRNAs per well.

   Loads one or more count CSVs, drops control wells, computes per-well
   gRNA fractions, sweeps thresholds to find the value producing the
   requested unique-count average, and plots both the sweep curve and
   the resulting per-plate heatmap.

   :param settings: dict with keys ``count_data`` (str or list of CSVs
       with ``grna``, ``count``, ``rowID``, ``columnID``),
       ``target_unique_count``, ``filter_column``, ``control_wells``,
       ``log_x`` and ``log_y``.
   :returns: the fraction threshold closest to the target unique count.


