Getting Started with OpenNano
=============================

Welcome to OpenNano! This guide will help you get started with installing and using the OpenNano package for analyzing NanoString GeoMx data.

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

To install OpenNano, use pip:

.. code-block:: bash

   pip install opennano

Alternatively, you can clone the repository and install it locally:

.. code-block:: bash

   git clone https://github.com/your-username/opennano.git
   cd opennano
   pip install .

Requirements
------------

Ensure you have the following dependencies installed:

- Python 3.8+
- pandas
- anndata
- numpy
- scipy
- matplotlib
- seaborn
- scikit-learn
- scanpy

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

The OpenNano package provides a seamless way to process NanoString GeoMx data and perform quality control (QC). Below is a quick walkthrough of the main features.

### Processing GeoMx Data

Use the `GeoMxProcessor` class to parse `.dcc`, `.pkc`, and GEO SOFT metadata files and create an `AnnData` object for downstream analysis.

.. code-block:: python

   from opennano.io import GeoMxProcessor

   processor = GeoMxProcessor(
       dcc_files="path/to/dcc_directory",
       pkc_file="path/to/probes.pkc",
       metadata_file="path/to/metadata.txt"
   )

   adata = processor.process()
   print(adata)
   # Output: AnnData object with n_obs x n_vars = <features> x <samples>

### Performing QC Checks

The `CountsQC` class allows you to perform quality control on the `AnnData` object. 

.. code-block:: python

   from opennano.qc import CountsQC

   qc = CountsQC(adata=adata)

   # Plot QC metrics
   qc.plot_qc_results()

   # Run all QC checks
   filtered_adata = qc.run_all_checks()
   print(filtered_adata)

Advanced Features
-----------------

- **Independent File Parsing**:
   You can parse `.dcc`, `.pkc`, and GEO SOFT metadata files separately using static methods like `read_dcc_file`, `read_pkc`, and `parse_geo_soft_metadata_with_identifier` in the `GeoMxProcessor` class.

   .. code-block:: python

      from opennano.io import GeoMxProcessor

      dcc_data = GeoMxProcessor.read_dcc_file("sample1.dcc")
      print(dcc_data["Code_Summary"])

- **Custom QC Thresholds**:
   Adjust QC thresholds directly when creating a `CountsQC` object:

   .. code-block:: python

      qc = CountsQC(
          adata=adata,
          minSegmentReads=500,
          percentTrimmed=85,
          percentAligned=80
      )

      filtered_adata = qc.run_all_checks()

Visualization
-------------

OpenNano provides rich visualization options for inspecting QC metrics and comparing data before and after filtering. Here is an example:

.. code-block:: python

   qc.plot_before_after_filtering()

Contributing
------------

Contributions are welcome! Please visit our GitHub repository to report issues or submit pull requests:

`GitHub Repository <https://github.com/Niamhck/opennano>`_

Support
-------

If you have any questions or need help, please check the documentation or contact the maintainers through GitHub Discussions.

Happy analyzing with OpenNano!