riptide-ffa 0.2.5__tar.gz → 0.2.7__tar.gz

riptide_ffa-0.2.7/.github/workflows/CI.yml

@@ -0,0 +1,40 @@
+name: CI
+
+on:
+  - push
+  - pull_request
+
+jobs:
+  # See: https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#example-running-a-job-within-a-container
+  continuous-integration:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12"]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          make install
+      - name: Build documentation
+        if: matrix.python-version == '3.12'
+        run: make docs
+      - name: Lint
+        run: make lint
+      - name: Test
+        run: |
+          make test
+      - name: Check source distribution
+        if: matrix.python-version == '3.12'
+        run: make check-sdist
+      - name: Upload coverage reports to Codecov
+        uses: codecov/codecov-action@v5
+        env:
+          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}

riptide_ffa-0.2.7/.github/workflows/publish.yml

@@ -0,0 +1,36 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          make install
+
+      - name: Test
+        run: make test
+
+      - name: Build source distribution
+        run: python -m build --sdist
+
+      - name: Upload to PyPI
+        env:
+          TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
+          TWINE_USERNAME: __token__
+        run: python -m twine upload dist/*.tar.gz

{riptide-ffa-0.2.5 → riptide_ffa-0.2.7}/.gitignore

@@ -1,13 +1,19 @@
-*.o
-*.so
-*.pyc
-__pycache__
+dist
+build
+.egg
+.nox
 .vscode
-*.egg-info
 .coverage
-.eggs
+__pycache__
+.mypy_cache
+docs/_build
 .pytest_cache
-tmp
-build
-dist
 pip-wheel-metadata
+.ipynb_checkpoints
+src/riptide/_version.py
+
+*.o
+*.so
+*.egg
+*.py[cod]
+*.egg-info

riptide_ffa-0.2.7/.readthedocs.yaml

@@ -0,0 +1,18 @@
+# Read the Docs configuration file for Sphinx projects
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.12"
+
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs
+
+sphinx:
+  configuration: docs/source/conf.py

{riptide-ffa-0.2.5 → riptide_ffa-0.2.7}/CHANGELOG.md

@@ -4,6 +4,20 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 0.2.7 - 2026-09-20
+
+Internal refactoring and improvements: Fix documentation, add CI stages to check source distribution build, add linting with `ruff` and make a general code cleanup pass.
+
+## 0.2.6 - 2026-09-10
+
+This version modernises the project layout and packaging, and fixes issues in candidate plotting and downsampled variance calculations.
+
+### Fixed
+
+- Candidate plots now normalise each sub-integration independently for better contrast, contributed by Dejiang Yin.
+- Corrected the downsampled variance calculation for factors very close to an integer, thanks to Francesco Coti Zelati for reporting the issue.
+
+
 ## 0.2.5 - 2023-12-23
 
 This version fixes an installation error on recent OSX versions, and a segmentation fault that triggers in some edge cases.

riptide_ffa-0.2.7/Makefile

@@ -0,0 +1,53 @@
+.DEFAULT_GOAL := help
+PKG = riptide-ffa
+DOCS_SPHINXOPTS = --fail-on-warning --nitpicky --keep-going
+
+check-sdist: ## Build and smoke-test the source distribution in a temporary virtualenv
+	@set -eu; \
+	tmpdir="$$(mktemp -d)"; \
+	on_exit() { \
+		status=$$?; \
+		if [ "$$status" -eq 0 ]; then \
+			printf '\033[1;32m✅ Source distribution smoke test passed\033[0m\n'; \
+		else \
+			printf '\033[1;31m❌ Source distribution smoke test failed\033[0m\n' >&2; \
+		fi; \
+		rm -rf "$$tmpdir"; \
+		exit "$$status"; \
+	}; \
+	trap on_exit EXIT; \
+	python -m build --sdist --outdir "$$tmpdir/dist"; \
+	python -m venv "$$tmpdir/venv"; \
+	"$$tmpdir/venv/bin/python" -m pip install "$$tmpdir"/dist/*.tar.gz; \
+	cd "$$tmpdir"; \
+	"$$tmpdir/venv/bin/python" -c "import riptide; print(riptide.__version__)"; \
+	"$$tmpdir/venv/bin/rffa" --help >/dev/null; \
+	"$$tmpdir/venv/bin/rseek" --help >/dev/null
+
+docs: ## Build clean HTML documentation in docs/build/html
+	$(MAKE) -C docs clean html SPHINXOPTS="$(DOCS_SPHINXOPTS)"
+
+install: ## Install the package in editable mode with dev and docs dependencies
+	pip install -e '.[dev,docs]'
+
+lint: ## Run the linter
+	ruff check src tests
+
+# GLORIOUS hack to autogenerate Makefile help
+# This simply parses the double hashtags that follow each Makefile command
+# https://marmelab.com/blog/2016/02/29/auto-documented-makefile.html
+help: ## Print this help message
+	@echo "Makefile help for ${PKG}"
+	@echo "===================================================================="
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-20s\033[0m %s\n", $$1, $$2}'
+
+test: ## Run the unit tests and print a coverage report
+	pytest --cov=src/ --cov-report=term-missing
+
+ci: ## Run all checks for continuous integration
+	$(MAKE) docs
+	$(MAKE) lint
+	$(MAKE) test
+	$(MAKE) check-sdist
+
+.PHONY: check-sdist docs install lint help test ci

riptide_ffa-0.2.7/PKG-INFO

@@ -0,0 +1,104 @@
+Metadata-Version: 2.4
+Name: riptide-ffa
+Version: 0.2.7
+Summary: Pulsar searching with the Fast Folding Algorithm (FFA)
+Author-email: Vincent Morello <vmorello@gmail.com>
+Maintainer-email: Vincent Morello <vmorello@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/v-morello/riptide
+Project-URL: Documentation, https://riptide-ffa.readthedocs.io
+Project-URL: Repository, https://github.com/v-morello/riptide
+Project-URL: Issues, https://github.com/v-morello/riptide/issues
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: C++
+Classifier: Operating System :: Unix
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Topic :: Scientific/Engineering :: Astronomy
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: astropy>=5.0
+Requires-Dist: matplotlib>=3.6
+Requires-Dist: numpy>=1.23
+Requires-Dist: pandas>=1.5
+Requires-Dist: pydantic<3,>=2
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: threadpoolctl>=3.1
+Provides-Extra: docs
+Requires-Dist: sphinx<8,>=7.4; python_version < "3.11" and extra == "docs"
+Requires-Dist: sphinx<9,>=8.2; python_version >= "3.11" and extra == "docs"
+Requires-Dist: sphinx-rtd-theme<4,>=3; extra == "docs"
+Provides-Extra: dev
+Requires-Dist: build>=1.0; extra == "dev"
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: ruff>=0.11; extra == "dev"
+Requires-Dist: twine>=4.0; extra == "dev"
+Dynamic: license-file
+
+[![arXiv](http://img.shields.io/badge/astro.ph-2004.03701-B31B1B.svg)](https://arxiv.org/abs/2004.03701)   ![License](https://img.shields.io/badge/License-MIT-green.svg)   ![Python versions](https://img.shields.io/pypi/pyversions/riptide-ffa.svg)  ![CI status](https://github.com/v-morello/riptide/actions/workflows/CI.yml/badge.svg?branch=master)   [![codecov](https://codecov.io/gh/v-morello/riptide/branch/master/graph/badge.svg)](https://codecov.io/gh/v-morello/riptide)
+
+# riptide
+
+__riptide__ ("sea**r**ch**i**ng for **p**ulsars in the **ti**me **d**omain") is a pulsar searching package implementing the Fast Folding Algorithm (FFA), the theoretically optimal search method for periodic signals. Its interface is entirely in python while the core algorithms are implemented in C. riptide provides:  
+
+* A library of functions and classes to use interactively to process dedispersed time series  
+* A pipeline executable to process a set of DM trials and output a list of candidate files and other useful data products  
+
+## Citation
+
+If using ``riptide`` contributes to a project that leads to a scientific publication, please cite the article:  
+["Optimal periodicity searching: Revisiting the Fast Folding Algorithm for large scale pulsar surveys"](https://arxiv.org/abs/2004.03701)
+
+
+## Sensitivity of the FFA
+
+The article covers the topic of the FFA's sensitivity in theory, here is a practical example on a faint source. Below is an L-band observation of [PSR J1932-3655](https://www.atnf.csiro.au/people/joh414/ppdata/1932-3655.html) from the [SUPERB survey](https://arxiv.org/abs/1706.04459), significantly offset from the true position of the source. The first plot was obtained by folding the observation using the known ephemeris of the pulsar with [PSRCHIVE](http://psrchive.sourceforge.net/). This is one of the faintest known pulsar instances identifiable in the survey.
+
+![psrchive_plot](docs/source/images/J1932-3655_psrchive_small.png "PSRCHIVE direct ephemeris folding")  
+
+And below is a blind detection of the pulsar, running `riptide` on the same observation:  
+![riptide_plot](docs/source/images/J1932-3655_blind_detection.png "riptide blind detection")
+
+
+## Documentation
+
+A quickstart guide, a pipeline configuration tutorial and the full API documentation can be found [here](https://riptide-ffa.readthedocs.io).
+
+## Installation
+
+The easiest method is to use pip install, which pulls the latest release from the python package index and installs all required dependencies:
+```
+pip install riptide-ffa
+```
+
+The alternative is to clone the repository, especially if you want the absolute latest version:
+```bash
+git clone https://github.com/v-morello/riptide
+```
+
+And then in the base directory of `riptide` run
+
+```bash
+make install
+```
+
+This runs ``pip install`` in [editable mode](https://pip.pypa.io/en/latest/reference/pip_install/#editable-installs), which means you can freely edit the code. It also installs the development and documentation dependencies. The installer adds links to two command-line apps in your python environment using [console_scripts entry points](https://python-packaging.readthedocs.io/en/latest/command-line-scripts.html):
+
+* `rffa`: The full end-to-end pipeline to search multiple DM trials, see below for details on how to use it.
+* `rseek`: A lightweight app to search a single time series and print significant candidates found, useful for quick data checks.
+
+You may check that it all works by typing:  
+```
+rffa -h
+rseek -h
+```
+And you should see the full help of both applications.
+
+
+
+

{riptide-ffa-0.2.5 → riptide_ffa-0.2.7}/README.md

@@ -1,4 +1,4 @@
-[![arXiv](http://img.shields.io/badge/astro.ph-2004.03701-B31B1B.svg)](https://arxiv.org/abs/2004.03701)   ![License](https://img.shields.io/badge/License-MIT-green.svg)   ![Python versions](https://img.shields.io/pypi/pyversions/riptide-ffa.svg)   [![Build Status](https://travis-ci.com/v-morello/riptide.svg?branch=master)](https://travis-ci.com/v-morello/riptide)   [![codecov](https://codecov.io/gh/v-morello/riptide/branch/master/graph/badge.svg)](https://codecov.io/gh/v-morello/riptide)
+[![arXiv](http://img.shields.io/badge/astro.ph-2004.03701-B31B1B.svg)](https://arxiv.org/abs/2004.03701)   ![License](https://img.shields.io/badge/License-MIT-green.svg)   ![Python versions](https://img.shields.io/pypi/pyversions/riptide-ffa.svg)  ![CI status](https://github.com/v-morello/riptide/actions/workflows/CI.yml/badge.svg?branch=master)   [![codecov](https://codecov.io/gh/v-morello/riptide/branch/master/graph/badge.svg)](https://codecov.io/gh/v-morello/riptide)
 
 # riptide
 
@@ -17,10 +17,10 @@ If using ``riptide`` contributes to a project that leads to a scientific publica
 
 The article covers the topic of the FFA's sensitivity in theory, here is a practical example on a faint source. Below is an L-band observation of [PSR J1932-3655](https://www.atnf.csiro.au/people/joh414/ppdata/1932-3655.html) from the [SUPERB survey](https://arxiv.org/abs/1706.04459), significantly offset from the true position of the source. The first plot was obtained by folding the observation using the known ephemeris of the pulsar with [PSRCHIVE](http://psrchive.sourceforge.net/). This is one of the faintest known pulsar instances identifiable in the survey.
 
-![psrchive_plot](images/J1932-3655_psrchive_small.png "PSRCHIVE direct ephemeris folding")  
+![psrchive_plot](docs/source/images/J1932-3655_psrchive_small.png "PSRCHIVE direct ephemeris folding")  
 
 And below is a blind detection of the pulsar, running `riptide` on the same observation:  
-![riptide_plot](images/J1932-3655_blind_detection.png "riptide blind detection")
+![riptide_plot](docs/source/images/J1932-3655_blind_detection.png "riptide blind detection")
 
 
 ## Documentation
@@ -45,7 +45,7 @@ And then in the base directory of `riptide` run
 make install
 ```
 
-This simply runs ``pip install`` in [editable mode](https://pip.pypa.io/en/latest/reference/pip_install/#editable-installs), which means you can freely edit the code. It also installs any required dependencies with ``pip`` that are not present already. The installer also adds links to two command-line apps in your python environment using [console_scripts entry points](https://python-packaging.readthedocs.io/en/latest/command-line-scripts.html):  
+This runs ``pip install`` in [editable mode](https://pip.pypa.io/en/latest/reference/pip_install/#editable-installs), which means you can freely edit the code. It also installs the development and documentation dependencies. The installer adds links to two command-line apps in your python environment using [console_scripts entry points](https://python-packaging.readthedocs.io/en/latest/command-line-scripts.html):
 
 * `rffa`: The full end-to-end pipeline to search multiple DM trials, see below for details on how to use it.
 * `rseek`: A lightweight app to search a single time series and print significant candidates found, useful for quick data checks.
@@ -60,4 +60,3 @@ And you should see the full help of both applications.
 
 
 
-

riptide_ffa-0.2.7/docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

riptide_ffa-0.2.7/docs/source/conf.py

@@ -0,0 +1,58 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+
+
+# -- Project information -----------------------------------------------------
+
+project = "riptide-ffa"
+copyright = "2021, Vincent Morello"
+author = "Vincent Morello"
+
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+# NOTE: sphinx.ext.autosectionlabel makes it easy to reference other
+# sections in the docs
+# See: https://stackoverflow.com/a/54843636
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.napoleon",
+    "sphinx_rtd_theme",
+    "sphinx.ext.autosectionlabel",
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ["_templates"]
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = []
+
+nitpick_ignore = [
+    ("py:class", "ndarray"),
+    ("py:class", "optional"),
+]
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = "sphinx_rtd_theme"
+
+pygments_style = "sphinx"

riptide_ffa-0.2.7/docs/source/docker.rst

@@ -0,0 +1,18 @@
+Docker Image
+============
+
+The riptide `Dockerfile`_ is located in the ``docker`` subdirectory. To build the image, clone the repository and in its base directory type:
+
+.. _`Dockerfile`: https://github.com/v-morello/riptide/blob/master/docker/Dockerfile
+
+.. code-block:: console
+
+    make docker
+
+Which builds an image named ``riptide-ffa``. Both python and ipython are installed within the docker image. To start a container:
+
+.. code-block:: console
+
+    docker run -it --rm riptide-ffa
+
+Feel free to adapt the Dockerfile to your needs. Refer to your favourite docker cheat sheet for further information.

riptide_ffa-0.2.7/docs/source/index.rst

@@ -0,0 +1,52 @@
+riptide: Finding pulsars with the Fast Folding Algorithm (FFA)
+==============================================================
+
+.. image:: http://img.shields.io/badge/astro.ph-2004.03701-B31B1B.svg
+   :target: https://arxiv.org/abs/2004.03701
+   :alt: arXiv
+  
+.. image:: https://github.com/v-morello/riptide/actions/workflows/CI.yml/badge.svg?branch=master
+   :alt: Build status
+  
+.. image:: https://codecov.io/gh/v-morello/riptide/branch/master/graph/badge.svg
+   :target: https://codecov.io/gh/v-morello/riptide
+   :alt: Coverage
+
+
+``riptide`` ("sea\ **r**\ ch\ **i**\ ng for **p**\ ulsars in the **ti**\ me **d**\ omain") is a pulsar searching
+package that implements the Fast Folding Algorithm (FFA), the theoretically optimal search method
+for periodic signals. Its interface is entirely in python while the core algorithms are implemented
+in C++. riptide provides:  
+
+* A library of functions and classes to manipulate and search individual dedispersed time series  
+* A pipeline executable to process a set of DM trials and output a list of candidate files, plots and other data products
+
+
+Citation
+--------
+
+If using ``riptide`` contributes to a project that leads to a scientific publication, please cite the article:  
+`Optimal periodicity searching: Revisiting the Fast Folding Algorithm for large scale pulsar surveys`__
+
+__ https://arxiv.org/abs/2004.03701
+
+
+.. toctree::
+   :maxdepth: 3
+   :caption: Contents:
+
+   installation
+   quickstart
+   kernfuncs
+   pipeline
+   docker
+   reference
+
+Indices and tables
+------------------
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
+
+

riptide_ffa-0.2.7/docs/source/installation.rst

@@ -0,0 +1,31 @@
+Installation
+============
+
+The easiest method is to use pip install, which pulls the latest release from PyPI and installs all required dependencies:
+
+.. code-block:: console
+
+   pip install riptide-ffa
+
+
+Alternatively you can clone the repository and run ``make install``
+
+.. code-block:: console
+
+   git clone https://github.com/v-morello/riptide
+   cd riptide/
+   make install
+
+This runs ``pip install`` in `editable mode`_, which means you can freely edit the code.
+It also installs the development and documentation dependencies. You can check that it all works
+by running the test suite in a Python or IPython console:
+
+    >>> import riptide
+    >>> riptide.test()
+
+.. _`editable mode`: https://pip.pypa.io/en/latest/reference/pip_install/#editable-installs
+
+There should also now be two command-line apps in your python environment:
+
+* ``rseek``: A lightweight app to search a single time series and print significant candidates found, useful for quick data checks. See :ref:`The rseek command-line app`.
+* ``rffa``: The full end-to-end pipeline to search multiple DM trials, see :ref:`Using the Pipeline`.

riptide_ffa-0.2.7/docs/source/kernfuncs.rst

@@ -0,0 +1,13 @@
+FFA kernel functions
+====================
+
+The python interface of ``riptide`` exposes some lower-level functions related to calculating the folding transform (interchangeably called FFA transform) of input data at some base integer period.
+There is also a kernel function to calculate S/N. These are:  
+
+* ``ffa2``: FFA transform of a two-dimensional input that represents a pulse stack. The ``m`` lines of the input represent pulses in chronological order, and the ``p`` columns represent the phase dimension  
+* ``ffa1``: FFA transform of a one-dimensional input, that represents a time series. The function simply selects the largest number of entire pulses that fit in the data, reshapes them into a two-dimensional array, and calls ``ffa2()``  
+* ``ffafreq``: Returns the trial folding frequencies corresponding to every line in the output of an FFA transform  
+* ``ffaprd``: Same as ``ffafreq``, but returns trial periods instead
+* ``boxcar_snr``: Compute the S/N ratio of pulse profile(s) by concolving them with a range of boxcar filters with different widths.
+
+See :ref:`API Reference` for further details.