meteor-maps 0.2.2__tar.gz

meteor_maps-0.2.2/.github/workflows/deploy.yml

@@ -0,0 +1,46 @@
+name: deploy
+
+on:
+  workflow_run:
+    branches:
+      - master
+    workflows:
+      - "tests"
+      - "mypy"
+      - "ruff"
+    types: 
+      - completed
+
+jobs:
+  deploy:
+    name: deploy-to-pypi
+    runs-on: ubuntu-latest
+    # only run if previous workflows were a success
+    # AND the commit starts with v (meaning it's a tag)
+    if: ${{ github.event.workflow_run.conclusion == 'success' && startsWith(github.event.workflow_run.head_commit.message, 'v') }}
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+
+      - name: install
+        run: |
+          git tag
+          pip install -U pip
+          pip install -U build twine
+          python -m build
+          twine check dist/*
+          ls -lh dist
+      - name: build and publish
+        run: twine upload dist/*
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.PYPI_API_KEY }}
+
+      - uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: true

meteor_maps-0.2.2/.github/workflows/lint.yml

@@ -0,0 +1,39 @@
+name: ruff
+
+on: [pull_request]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11"]
+    
+    steps:
+    - name: Cancel Previous Runs
+      uses: styfle/cancel-workflow-action@0.12.1
+      with:
+        access_token: ${{ github.token }}
+
+    - 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 dependencies
+      run: |
+        python -m pip install --upgrade pip
+    
+    - name: Lint with Ruff
+      run: |
+        pip install ruff
+        ruff check --output-format=github .
+    
+    - name: Upload coverage to Codecov  
+      uses: codecov/codecov-action@v3
+      with:
+        file: ./coverage.xml
+        flags: unittests

meteor_maps-0.2.2/.github/workflows/mypy.yml

@@ -0,0 +1,35 @@
+name: mypy
+
+on: [pull_request]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11"]
+    
+    steps:
+    - name: Cancel Previous Runs
+      uses: styfle/cancel-workflow-action@0.12.1
+      with:
+        access_token: ${{ github.token }}
+        
+    - 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 dependencies
+      run: |
+        python -m pip install --upgrade pip
+
+    - name: mypy
+      run: |
+        pip install mypy
+        pip install '.[tests]'
+        mkdir .mypy_cache
+        mypy --install-types --non-interactive meteor/ test/

meteor_maps-0.2.2/.github/workflows/tests.yml

@@ -0,0 +1,55 @@
+name: tests
+
+on:
+  pull_request:
+  schedule:
+    - cron: "0 12 * * 1" # monday at noon GMT
+
+jobs:
+  build:
+    name: ${{ matrix.platform }}
+    runs-on: ${{ matrix.platform }}
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version:
+          - '3.11'
+        platform:
+          - ubuntu-latest
+          - macos-latest
+          - windows-latest
+    
+    steps:
+    - name: Cancel Previous Runs
+      uses: styfle/cancel-workflow-action@0.12.1
+      with:
+        access_token: ${{ github.token }}
+
+    - name: Checkout
+      uses: actions/checkout@v4
+      with:
+        lfs: true
+
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+        
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+    
+    - name: Test with pytest
+      run: |
+        pip install '.[tests]'
+        pytest test/
+    
+    - name: Upload coverage to Codecov  
+      uses: codecov/codecov-action@v4
+      env:
+        CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
+      with:
+        file: ./coverage.xml
+        flags: unittests
+        name: codecov-umbrella
+        fail_ci_if_error: true

meteor_maps-0.2.2/.gitignore

@@ -0,0 +1,171 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# large crystallography files -- some of which are used in tests
+# large files are accessed via github LFS
+*.ccp4
+*.map
+*.mtz
+*.pdb
+*.cif
+
+# C extensions
+*.so
+
+# Distribution / packaging
+_version.py
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/

meteor_maps-0.2.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Alisia Fadini and T. J. Lane
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

meteor_maps-0.2.2/PKG-INFO

@@ -0,0 +1,17 @@
+Metadata-Version: 2.1
+Name: meteor-maps
+Version: 0.2.2
+Summary: denoise crystallographic difference maps
+Author-email: Alisia Fadini <af840@cam.ac.uk>, Thomas Lane <thomas.lane@desy.de>
+Requires-Python: >=3.11
+License-File: LICENSE
+Requires-Dist: numpy>=1.26
+Requires-Dist: scipy>=1.14.0
+Requires-Dist: gemmi>=0.6.6
+Requires-Dist: scikit-image>=0.24.0
+Requires-Dist: reciprocalspaceship>=1.0.2
+Requires-Dist: structlog>=24.4.0
+Provides-Extra: tests
+Requires-Dist: pytest; extra == "tests"
+Requires-Dist: pytest-cov; extra == "tests"
+Requires-Dist: pytest-xdist; extra == "tests"

meteor_maps-0.2.2/README.md

@@ -0,0 +1,58 @@
+# METEOR
+Map Enhancement Tools for Ephemeral Occupancy Refinement
+----------
+
+[![Pytest](https://github.com/alisiafadini/meteor/actions/workflows/tests.yml/badge.svg)](https://github.com/your_username/your_repo/actions/workflows/tests.yml)
+[![Mypy](https://github.com/alisiafadini/meteor/actions/workflows/mypy.yml/badge.svg)](https://github.com/your_username/your_repo/actions/workflows/mypy.yml)
+[![Ruff](https://github.com/alisiafadini/meteor/actions/workflows/lint.yml/badge.svg)](https://github.com/your_username/your_repo/actions/workflows/lint.yml)
+[![codecov](https://codecov.io/gh/alisiafadini/meteor/graph/badge.svg?token=NCYMP06MNS)](https://codecov.io/gh/alisiafadini/meteor)
+
+`meteor` is a tool for computing crystallographic difference maps. 
+
+`meteor` specializes the robust identification of weak signals arising from minor but scientifically interesting populations, such as bound ligands or changes that occur in time-resolved experiments. That said, if you need an difference map, `meteor` can do it!
+
+
+## quickstart
+
+❗ `meteor` is currently **in beta**. We re-wrote everything recently, moving from a research code to something that can be robustly used as a tool. If you are willing to put up with a few sharp edges, it would be great if you give it a spin and then send us feedback: on how easy/not it was to use and what kinds of scientific results you obtain.
+
+Finally: a word of caution. Expect changes in the coming weeks as we stress test the code. You might want to consider this before publishing any results with `meteor` until we exit `beta`. 
+
+In that vein, for now please install the current master branch as per the following instructions. We'll have a sane
+first stable version soon, which will be deployed straight to `PyPI` and `conda-forge`. Stay posted.
+
+First, we recommend you make a new environment. For conda users,
+```
+conda create --name meteor python==3.11 --yes
+conda activate meteor
+```
+
+Then install from github,
+```
+pip install git+https://github.com/alisiafadini/meteor
+```
+
+Once installed, you will have two command-line scripts. Ask for more info using `-h`:
+```
+meteor.diffmap -h
+meteor.phaseboost -h
+```
+which compute denoised difference maps using the constant-phase approximation _vs._ iterative phase retrieval, respectively.
+
+
+## philosophy: better science through automation
+
+`meteor` aims to:
+
+1. maximize signal to noise
+2. be objective and reproducible (minimize user choice & bias)
+3. be easy to use
+
+Aim 1 is met using structure factor amplitude weighting (e.g. k-weighting, existing art) and TV denoising (new in the context of crystallography). Aims 2 and 3 are met through automatically setting parameters using negentropy maximization. For all the details, see our paper (coming soon to a preprint server near you).
+
+
+## isomorphous data, please
+
+METEOR is only for isomorphous difference maps, meaning the lattices/symmetries of the `native` and `derivative` datasets are comparable. If you need to compare non-isomorphous lattices, check out [matchmaps](https://github.com/rs-station/matchmaps).
+
+

meteor_maps-0.2.2/meteor/__init__.py

@@ -0,0 +1,3 @@
+__all__ = ["__version__", "version"]
+
+from ._version import __version__, version

meteor_maps-0.2.2/meteor/_version.py

@@ -0,0 +1,16 @@
+# file generated by setuptools_scm
+# don't change, don't track in version control
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Tuple, Union
+    VERSION_TUPLE = Tuple[Union[int, str], ...]
+else:
+    VERSION_TUPLE = object
+
+version: str
+__version__: str
+__version_tuple__: VERSION_TUPLE
+version_tuple: VERSION_TUPLE
+
+__version__ = version = '0.2.2'
+__version_tuple__ = version_tuple = (0, 2, 2)

meteor_maps-0.2.2/meteor/diffmaps.py

@@ -0,0 +1,183 @@
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+import numpy as np
+import reciprocalspaceship as rs
+
+from .rsmap import Map, _assert_is_map
+from .settings import DEFAULT_KPARAMS_TO_SCAN, MAP_SAMPLING
+from .utils import filter_common_indices
+from .validate import ScalarMaximizer, negentropy
+
+
+def set_common_crystallographic_metadata(map1: Map, map2: Map, *, output: Map) -> None:
+    if hasattr(map1, "cell"):
+        if hasattr(map2, "cell") and (map1.cell != map2.cell):
+            msg = f"`map1.cell` {map1.cell} != `map2.cell` {map2.cell}"
+            raise AttributeError(msg)
+        output.cell = map1.cell
+
+    if hasattr(map1, "spacegroup"):
+        if hasattr(map2, "spacegroup") and (map1.spacegroup != map2.spacegroup):
+            msg = f"`map1.spacegroup` {map1.spacegroup} != "
+            msg += f"`map2.spacegroup` {map2.spacegroup}"
+            raise AttributeError(msg)
+        output.spacegroup = map1.spacegroup
+
+
+def compute_difference_map(derivative: Map, native: Map) -> Map:
+    """
+    Computes amplitude and phase differences between native and derivative structure factor sets.
+
+    It converts the amplitude and phase pairs from both the native and derivative structure factor
+    sets into complex numbers, computes the difference, and then converts the result back
+    into amplitudes and phases.
+
+    If uncertainty columns are provided for both native and derivative data, it also propagates the
+    uncertainty of the difference in amplitudes.
+
+    Parameters
+    ----------
+    derivative: Map
+        the derivative amplitudes, phases, uncertainties
+    native: Map
+        the native amplitudes, phases, uncertainties
+
+    Returns
+    -------
+    diffmap: Map
+        map corresponding to the complex difference (derivative - native)
+    """
+    _assert_is_map(derivative, require_uncertainties=False)
+    _assert_is_map(native, require_uncertainties=False)
+
+    derivative, native = filter_common_indices(derivative, native)  # type: ignore[assignment]
+
+    delta_complex = derivative.complex_amplitudes - native.complex_amplitudes
+    delta = Map.from_structurefactor(delta_complex, index=native.index)
+
+    set_common_crystallographic_metadata(derivative, native, output=delta)
+
+    if derivative.has_uncertainties and native.has_uncertainties:
+        prop_uncertainties = np.sqrt(derivative.uncertainties**2 + native.uncertainties**2)
+        delta.set_uncertainties(prop_uncertainties)
+
+    return delta
+
+
+def compute_kweights(difference_map: Map, *, k_parameter: float) -> rs.DataSeries:
+    """
+    Compute weights for each structure factor based on DeltaF and its uncertainty.
+
+    Parameters
+    ----------
+    difference_map: Map
+        A map of structure factor differences (DeltaF).
+    k_parameter: float
+        A scaling factor applied to the squared `df` values in the weight calculation.
+
+    Returns
+    -------
+    weights: rs.DataSeries
+        A series of computed weights, where higher uncertainties and larger differences lead to
+        lower weights.
+    """
+    _assert_is_map(difference_map, require_uncertainties=True)
+
+    inverse_weights = (
+        1
+        + (difference_map.uncertainties**2 / (difference_map.uncertainties**2).mean())
+        + k_parameter * (difference_map.amplitudes**2 / (difference_map.amplitudes**2).mean())
+    )
+    return 1.0 / inverse_weights
+
+
+def compute_kweighted_difference_map(derivative: Map, native: Map, *, k_parameter: float) -> Map:
+    """
+    Compute k-weighted derivative - native structure factor map.
+
+    This function first computes the standard difference map using `compute_difference_map`.
+    Then, it applies k-weighting to the amplitude differences based on the provided `k_parameter`.
+
+    Assumes amplitudes have already been scaled prior to invoking this function.
+
+    Parameters
+    ----------
+    derivative: Map
+        the derivative amplitudes, phases, uncertainties
+    native: Map
+        the native amplitudes, phases, uncertainties
+
+    Returns
+    -------
+    diffmap: Map
+        the k-weighted difference map
+    """
+    # require uncertainties at the beginning
+    _assert_is_map(derivative, require_uncertainties=True)
+    _assert_is_map(native, require_uncertainties=True)
+
+    difference_map = compute_difference_map(derivative, native)
+    weights = compute_kweights(difference_map, k_parameter=k_parameter)
+
+    difference_map.amplitudes *= weights
+    difference_map.uncertainties *= weights
+
+    return difference_map
+
+
+def max_negentropy_kweighted_difference_map(
+    derivative: Map,
+    native: Map,
+    *,
+    k_parameter_values_to_scan: np.ndarray | Sequence[float] = DEFAULT_KPARAMS_TO_SCAN,
+) -> rs.DataSet:
+    """
+    Compute k-weighted differences between native and derivative amplitudes and phases.
+
+    Determines an "optimal" k_parameter, between 0.0 and 1.0, that maximizes the resulting
+    difference map negentropy. Assumes that scaling has already been applied to the amplitudes
+    before calling this function.
+
+    Parameters
+    ----------
+    derivative: Map
+        the derivative amplitudes, phases, uncertainties
+    native: Map
+        the native amplitudes, phases, uncertainties
+    k_parameter_values_to_scan : np.ndarray | Sequence[float]
+        The values to scan to optimize the k-weighting parameter, by default is 0.00, 0.01 ... 1.00
+
+    Returns
+    -------
+    kweighted_dataset: rs.DataSet
+        dataset with added columns
+
+    opt_k_parameter: float
+        optimized k-weighting parameter
+    """
+    _assert_is_map(derivative, require_uncertainties=True)
+    _assert_is_map(native, require_uncertainties=True)
+
+    def negentropy_objective(k_parameter: float) -> float:
+        kweighted_dataset = compute_kweighted_difference_map(
+            derivative,
+            native,
+            k_parameter=k_parameter,
+        )
+        k_weighted_map = kweighted_dataset.to_ccp4_map(map_sampling=MAP_SAMPLING)
+        k_weighted_map_array = np.array(k_weighted_map.grid)
+        return negentropy(k_weighted_map_array)
+
+    maximizer = ScalarMaximizer(objective=negentropy_objective)
+    maximizer.optimize_over_explicit_values(arguments_to_scan=k_parameter_values_to_scan)
+    opt_k_parameter = float(maximizer.argument_optimum)
+
+    kweighted_dataset = compute_kweighted_difference_map(
+        derivative,
+        native,
+        k_parameter=opt_k_parameter,
+    )
+
+    return kweighted_dataset, opt_k_parameter