Skip to content

Commit

Permalink
Merge pull request #15 from phac-nml/docs
Browse files Browse the repository at this point in the history
Updating the Documentation for v.2.0.0
  • Loading branch information
emarinier authored Nov 5, 2024
2 parents 1e7ac51 + a078bba commit 7bb5bfc
Show file tree
Hide file tree
Showing 42 changed files with 214 additions and 301 deletions.
60 changes: 30 additions & 30 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,162 +2,162 @@

All notable changes to Neptune will be documented in this file.

## 2.0.0 ##
## 2.0.0

2024-10-21

This release updates Neptune to Python3, removes DRMAA support, fixes a crash when no signatures are produced, and updates the installation process.

### Changed ###
### Changed

- Python3 has replaced Python2.
- Improved and updated the installation process.

### Fixed ###
### Fixed

- Fixed a crash that occurred when candidate signatures were of such low quality (as a consequence of ambiguous sequence characters) that these regions could not be aligned with themselves using BLAST.

### Removed ###
### Removed

- DRMAA support.

## 1.2.5 ##
## 1.2.5

2017-05-03

This release provides fixes for ambiguous crashes and improvements to the code quality.

### Changed ###
### Changed

- We have made an effort to improve the readability of function comments in the source code.

### Fixed ###
### Fixed

- When running Neptune in parallel (non-DRMAA mode), runtime errors in forked jobs now correctly inform the calling process instead of hanging forever with no meaningful error message. Additionally, the runtime error message is reported to the user. This relates the a known error in Python 2.7 (https://bugs.python.org/issue9400).
- Inputs containing no A, C, G, or T characters will now cause an appropriate runtime error with an informative message about this problem.
- Lowercase characters are no longer ingnored when calculating the GC content of inputs.

## 1.2.4 ##
## 1.2.4

2017-02-27

This release makes several small improvements, including: reducing the standard output clutter, adding timings to stages, and updating the documentation.

### Added ###
### Added

- Links in the README to the manual.
- Walkthrough to the manual.
- Example data to test the software.
- Timings for stages.

### Changed ###
### Changed

- Improved clarity in manual.
- Codeblocks in the manual.

### Removed ###
### Removed

- Considerable clutter has been removed from standard output.

## 1.2.3 ##
## 1.2.3

2016-07-11

This release simplifies the installation process.

### Added ###
### Added

- A script for automatically installing Debian dependencies.

### Changed ###
### Changed

- The dependencies have changed. Several are now installed as part of Neptune.
- The Neptune installation no longer requires security privilages.
- Neptune may be installed multiple times in multiple locations.
- NumPy and SciPy are now installed using pip.

### 1.2.2 ###
## 1.2.2

2016-04-06

This release includes some Galaxy improvements and fixes a signature scoring problem.

### Changed ###
### Changed

- Galaxy XML files have been updated to use different packages of Python.

### Fixed ###
### Fixed

- A bug confusing inclusion and exclusion has been fixed.

## 1.2.1 ##
## 1.2.1

2016-03-23

This release of Neptune adds support for Galaxy.

### Added ###
### Added

- Galaxy-related files: capsules, XML files.

### Changed ###
### Changed

- Neptune.py and Execution.py are now compatible with Galaxy.

## 1.2.0 ##
## 1.2.0

2016-03-18

This release of Neptune allows for execution on a single machine without requiring DRMAA. Furthermore, several command line parameters have been modified.

### Added ###
### Added

- Neptune may be run in parallel on a single machine without DRMAA.
- "--version" command line option.

### Changed ###
### Changed

- Several command-line parameters have been changed.
- The "--parallelization" / "-p" parameter effects all parallelization.
- The exclusion score is now displayed as a positive number.

## 1.1.1 ##
## 1.1.1

2016-02-24

This release of Neptune updates the installation instructions to be more informative.

### Changed ###
### Changed

- Updated README and manual installation instructions.
- Modified the style of code examples in the manual.

## 1.1.0 ##
## 1.1.0

2016-01-19

This release of Neptune introduces a simple signature consolidation step, which consolidates signatures produced from multiple files into a single file. Furthermore, the software has been updated to be compatible with the Slurm scheduler.

### Added ###
### Added

- Neptune now automatically consolidates signatures into a single file.
- DRMAA job names.
- Neptune now maintains DRMAA log files.
- Added the ability to specify the BLAST seed size.

### Changed ###
### Changed

- The run receipt has been reorganized.
- Removed some unneeded output files.
- Removed some unneeded print statements.
- Removed the --verbose parameter. There was no functionality.

### Fixed ###
### Fixed

- Neptune is now compatible with the Slurm scheduler.
- Updated PEP8/Flake8 code compliance (W503).

## 1.0.0 ##
## 1.0.0

2015-11-18

Expand Down
2 changes: 1 addition & 1 deletion NOTICE.txt
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
Neptune

Copyright Government of Canada 2015-2017
Copyright Government of Canada 2015-2024

Written by: Eric Marinier, Public Health Agency of Canada,
National Microbiology Laboratory
Expand Down
106 changes: 59 additions & 47 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,18 +1,8 @@
# Introduction #

A genomic signature is a genomic locus that is sufficiently represented in an
inclusion group, and sufficiently absent from a background, or exclusion
group. A signature might correlate genomic features with phenotypic traits,
such as the presence of a gene with increased organism pathogenicity.

Neptune locates genomic signatures using an exact k-mer matching strategy while
accommodating k-mer mismatches. The software identifies sequences that are
sufficiently represented within inclusion targets and sufficiently absent from
exclusion targets. The signature discovery process is accomplished using
probabilistic models instead of heuristic strategies. Neptune may be leveraged
to reveal discriminatory signature sequences to uniquely delineate one group of
organisms, such as isolates associated with a disease cluster or event, from
unrelated sporadic or environmental microbes.
A genomic signature is a genomic locus that is sufficiently represented in an inclusion group, and sufficiently absent from a background, or exclusion group. A signature might correlate genomic features with phenotypic traits, such as the presence of a gene with increased organism pathogenicity.

Neptune locates genomic signatures using an exact k-mer matching strategy while accommodating k-mer mismatches. The software identifies sequences that are sufficiently represented within inclusion targets and sufficiently absent from exclusion targets. The signature discovery process is accomplished using probabilistic models instead of heuristic strategies. Neptune may be leveraged to reveal discriminatory signature sequences to uniquely delineate one group of organisms, such as isolates associated with a disease cluster or event, from unrelated sporadic or environmental microbes.

# Resources #

Expand All @@ -22,31 +12,64 @@ unrelated sporadic or environmental microbes.

# Release #

**Neptune 1.2.5**
**Neptune 2.0.0 - 2024-10-21**

This release provides fixes for ambiguous crashes as a consequence of inputs
containing no A, C, G, or T characters, and also makes improvements to the
code quality.
This release updates Neptune to Python3, removes DRMAA support, fixes a crash when no signatures are produced, and updates the installation process.

# Installation #

It is strongly recommended you refer to the
[documentation](https://phac-nml.github.io/neptune/install/) for full
installation instructions. Neptune may be installed on any 64-bit Linux system
using Bioconda, preferably with [Mamba](https://mamba.readthedocs.io/en/latest/installation/mamba-installation.html) or with the Mamba resolver under Conda:
## Python 3

Ensure your version of Python is compatible (python>=3.10):

`python --version`

You may wish to use [Conda](https://docs.conda.io/projects/conda/en/latest/user-guide/getting-started.html) to create an environment specifically for this purpose:

`conda create --name neptune 'python>=3.10'`
`conda activate neptune`

## pip

Ensure you can run pip:

`pip --version` or `python -m pip --version`

If pip is unavailable, please refer to [these instructions](https://packaging.python.org/en/latest/tutorials/installing-packages/) on how to install pip.

## BLAST

Neptune requires BLAST to be manually installed and made available as a command-line program:

1. Install [Bioconda](https://bioconda.github.io/)
2. Create an environment for Neptune and install within it: `mamba create -n neptune bioconda::neptune -c conda-forge`
3. Activate the environment: `mamba activate neptune`
4. Test the install: `neptune --version`
`sudo apt-get install ncbi-blast+`

If you run into problems installing Neptune with Conda / Mamba, you can try the following:
You can verify BLAST was installed by ensuring the follow commands are available:

- Modify your `~/.condarc` file to have `channel_priority: flexible`
- Modify your conda solver within `~/.condarc` to use Mamba: `solver: libmamba`
`makeblastdb -h`
`blastn -h`

Neptune may also be installed directly and instructions are available in the
[documentation](https://phac-nml.github.io/neptune/install/).
## Neptune and Dependencies

After downloading Neptune's source files, you can install Neptune and all of its pip dependencies with the following:

`pip install /path/to/neptune_directory/` or `pip install .`

**CAUTION**: If you attempt `pip install neptune` (not interpreted as a file path), then you'll download a different package that's also named "neptune" that's available directly from pip.

The following packages and their dependencies will be installed:

- numpy
- scipy
- biopython
- neptune

You can verify the installation was successful with the following:

`neptune --version`

And you can test the installation with simple test inputs with the following:

`neptune -i tests/data/example/inclusion/ -e tests/data/example/exclusion/ -o output`

# Running Neptune #

Expand All @@ -59,9 +82,7 @@ A simple example of running Neptune:
neptune --inclusion /path/to/inclusion/ --exclusion /path/to/exclusion/
--output /path/to/output/

Please refer to the
[documentation](https://phac-nml.github.io/neptune/parameters/) for more
details.
Please refer to the [documentation](https://phac-nml.github.io/neptune/parameters/) for more details.

# Contact #

Expand All @@ -71,23 +92,14 @@ details.

Neptune

Copyright Government of Canada 2015-2017
Copyright Government of Canada 2015-2024

Written by: Eric Marinier, Public Health Agency of Canada,
National Microbiology Laboratory
Written by: Eric Marinier, Public Health Agency of Canada, National Microbiology Laboratory

Funded by the National Micriobiology Laboratory and the Genome Canada / Alberta
Innovates Bio Solutions project "Listeria Detection and Surveillance
using Next Generation Genomics"
Funded by the National Micriobiology Laboratory and the Genome Canada / Alberta Innovates Bio Solutions project "Listeria Detection and Surveillance using Next Generation Genomics"

Licensed under the Apache License, Version 2.0 (the "License"); you may not use
this work except in compliance with the License. You may obtain a copy of the
License at:
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this work except in compliance with the License. You may obtain a copy of the License at:

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed
under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
CONDITIONS OF ANY KIND, either express or implied. See the License for the
specific language governing permissions and limitations under the License.

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
8 changes: 4 additions & 4 deletions docs/examples.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Examples #
# Examples

## Basic Execution ##
## Basic Execution

The following basic example will report all of the signatures that are sufficiently shared by the (FASTA) sequences in the inclusion directory and sufficiently absent from the (FASTA) sequences in the exclusion directory. Neptune will automatically calculate many of the parameters used in this execution.

Expand All @@ -17,7 +17,7 @@ The output of immediate interest will be located in the follow file:

This file will contain a consolidated list of signatures, sorted by their Neptune score, which is a combined estimate of sensitivity and specificity. The signatures with higher scores, near the top of the file, are considered the most discriminatory signatures.

## Faster Execution ##
## Faster Execution

The following example highlights options that allow Neptune to run faster when running in parallel mode (default). It will attempt to run Neptune on 16 parallel processes (`--parallelization`) and parallelize *k*-mer counting and aggregation into 64 tasks (`--organization`) distributed over the 16 parallel processes available.

Expand All @@ -30,7 +30,7 @@ neptune
--organization 3
```

## Specifying File Locations ##
## Specifying File Locations

You may wish to specify particular files used in signature discovery. This may be important when specifying references for signature extraction:

Expand Down
23 changes: 0 additions & 23 deletions docs/extra.css
Original file line number Diff line number Diff line change
@@ -1,23 +0,0 @@
.bs-sidenav {
font-size: 16px;
}

.navbar {
font-size: 16px;
}

.navbar-default {
background-color: #343838;
}

.navbar .dropdown-menu>li>a, .navbar .dropdown-menu>li>a:focus {
font-size: 14px;
}

table {
font-size: 13px;
}

body {
font-size: 14px;
}
Loading

0 comments on commit 7bb5bfc

Please sign in to comment.