emdbva 0.0.1.dev139__tar.gz → 0.0.1.dev143__tar.gz

{emdbva-0.0.1.dev139/emdbva.egg-info → emdbva-0.0.1.dev143}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: emdbva
-Version: 0.0.1.dev139
+Version: 0.0.1.dev143
 Summary: CryoEM validation toolkit
 Home-page: https://test.pypi.org/project/va/
 Author: Zhe Wang

{emdbva-0.0.1.dev139 → emdbva-0.0.1.dev143/emdbva.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: emdbva
-Version: 0.0.1.dev139
+Version: 0.0.1.dev143
 Summary: CryoEM validation toolkit
 Home-page: https://test.pypi.org/project/va/
 Author: Zhe Wang

{emdbva-0.0.1.dev139 → emdbva-0.0.1.dev143}/emdbva.egg-info/SOURCES.txt

@@ -8,9 +8,11 @@ emdbva.egg-info/dependency_links.txt
 emdbva.egg-info/entry_points.txt
 emdbva.egg-info/requires.txt
 emdbva.egg-info/top_level.txt
+va/PATHS_codon_airflow.py
 va/__init__.py
 va/mainva.py
 va/preparation.py
+va/prepareandrun_codon_airflow.py
 va/qscores.csv
 va/validationanalysis.py
 va/version.py

{emdbva-0.0.1.dev139 → emdbva-0.0.1.dev143}/setup.py

@@ -20,7 +20,7 @@ setup(
     version=__version__,
     packages=find_packages(),
     exclude_package_data={
-        'va': ['test/*', 'va/onedepva.py', 'core/*', 'proc/*', 'validation/*', 'test_data/*'],
+        'va': ['test/*', 'core/*', 'proc/*', 'validation/*', 'test_data/*'],
     },
     include_package_data=True,
     author="Zhe Wang",

emdbva-0.0.1.dev143/va/PATHS_codon_airflow.py

@@ -0,0 +1,80 @@
+"""
+PATHS.py
+
+
+PATHS is used to input and output directories of validation
+analysis.
+
+Copyright [2013] EMBL - European Bioinformatics Institute
+Licensed under the Apache License, Version 2.0 (the
+"License"); you may not use this file 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.
+
+"""
+
+__author__ = 'Zhe Wang'
+__email__ = 'zhe@ebi.ac.uk'
+__date__ = '2022-06-14'
+
+# ENT file source path
+ENTSOURCE = '/nfs/msd/work2/ftp/pdb/data/structures/all/pdb/'
+
+# VTP file source path
+VTPSOURCE = '/nfs/pdbe_staging/pdbe_data/development/staging/em/'
+
+# CIF file source path
+# CIFSOURCE = '/nfs/production/gerard/pdbe/prerelease/current/ftp/pdb/data/structures/divided/mmCIF/'
+# CIFSOURCE = '/nfs/ftp/public/.staging/pdbe-G79Bblrm/projects/pdb/staging/data/structures/all/mmCIF/'
+# CIFSOURCE = '/hps/nobackup/pdbe/nfs_prod/ftp/data/structures/all/mmCIF/'
+CIFSOURCE = '/nfs/production/gerard/pdbe/ftp/pdb/data/structures/all/mmCIF/'
+
+MAP_SERVER_PATH = '/hps/nobackup/gerard/emdb/va/entry_results/'
+
+# Chimera path
+# CHIMERA = '/hps/nobackup/gerard/emdb/va/external/chimerax/usr/libexec/UCSF-ChimeraX/bin/ChimeraX'
+CHIMERA = '/hps/nobackup/gerard/emdb/va/external/chimera110/usr/libexec/UCSF-ChimeraX/bin/ChimeraX'
+
+# Original or old Chimera
+OCHIMERA = '/hps/nobackup/gerard/emdb/va/external/chimera/bin/chimera'
+
+# For ebi server to copy data for VA
+# VASOURCE = '/nfs/msd/em/ftp_rsync/staging/structures/'
+# VASOURCE = '/nfs/production/gerard/emdb/archive/staging/structures/'
+# VASOURCE = '/hps/nobackup/gerard/emdb/archive/local/structures/'
+VASOURCE = '/nfs/production/gerard/emdb/archive2/local/structures/'
+
+# VAPATH
+VAPATH = '/hps/nobackup/gerard/emdb/va_airflow/Validation-Analysis/va/'
+
+# Jsons and images are copied to here for display purpose
+FORDISPLAY = '/nfs/nobackup/msd/em_va/development/'
+
+# Proshade path
+PROSHADEPATH = '/hps/software/users/gerard/emdb/va/external/ccpem/ccpem-1.6.0/bin/proshade'
+
+# Meshmaker path
+MESHMAKERPATH = '/nfs/msd/em/software/meshmakertest/meshmaker/build/meshmaker'
+
+# VA production path
+VA_PROD_PATH = '/nfs/public/rw/pdbe/httpd-em/sessions-prod/validation_analysis'
+
+# VA staging path
+VA_STAG_PATH = '/nfs/public/rw/pdbe/httpd-em/sessions/validation_analysis'
+
+# Strudel lib
+LIB_STRUDEL_ROOT = '/hps/nobackup/gerard/emdb/va/external/strudel_motiflib/strudel-lib.4_0.5px'
+
+# 3DFSC fake to take positions
+THREEDFSC_ROOT = '/Users/zhe/Downloads/Anisotropy/ThreeDFSC/ThreeDFSC_Start.py'
+
+# ResMap
+# RESMAP = '/hps/nobackup/gerard/emdb/va/external/resmap/ResMap_project/ResMap.py'
+RESMAP = '/hps/software/users/gerard/emdb/va/external/ccpem/ccpem-1.6.0/bin/relion_postprocess'

{emdbva-0.0.1.dev139 → emdbva-0.0.1.dev143}/va/mainva.py

@@ -3,8 +3,10 @@
 """
 mainva.py
 
-mainva class used to run the main function of validation
-analysis
+Entry points and orchestration helpers for the main VA pipeline.
+
+This module wires together preparation, validation analysis, and
+logging for the standard package-level VA workflow.
 
 Copyright [2013] EMBL - European Bioinformatics Institute
 Licensed under the Apache License, Version 2.0 (the
@@ -121,9 +123,9 @@ def allruns(validationobj, runs):
     if 'symmetry' in runs:
         validationobj.symmetry()
 
-    # Strudel
-    if 'strudel' in runs:
-        validationobj.strudel()
+    # Strudel (turning off)
+    # if 'strudel' in runs:
+    #     validationobj.strudel()
 
     # Q-score
     if 'qscore' in runs:
@@ -170,6 +172,7 @@ def inallruns(validationobj, runs):
     """
 
     def without_strudel():
+        """Run the selected validation steps other than Strudel."""
         # Projections
         if 'projection' in runs:
             validationobj.orthogonal_projections()
@@ -255,6 +258,7 @@ def inallruns(validationobj, runs):
         return None
 
     def strudel_only():
+        """Run the selected Strudel validation step."""
         # Strudel
         if 'strudel' in runs:
             validationobj.strudel()
@@ -333,6 +337,11 @@ def reconfigure_logging(temp_logger, buffer, log_file):
 
 # @profile
 def main():
+    """Run the main VA command-line entry point.
+
+    This function parses the CLI arguments, builds the preparation and
+    validation objects, and drives the configured validation runs.
+    """
 
     start_first = timeit.default_timer()
 
@@ -443,4 +452,3 @@ def main():
 
 if __name__ == '__main__':
     main()
-

{emdbva-0.0.1.dev139 → emdbva-0.0.1.dev143}/va/metrics/bars.py

@@ -1,3 +1,5 @@
+"""Calculate score percentiles and generate metric comparison plots."""
+
 import os.path
 import json
 import pandas as pd
@@ -317,6 +319,22 @@ def plot_bar_mat(a, b, qmin, qmax, qscore, work_dir, plot_name, score_type, resb
 
 
 def bar(new_entry_dict, score_type, work_dir, score_dir, plot_name, update_bin_file=None):
+    """Calculate whole-dataset and resolution-relative score percentiles.
+
+    Args:
+        new_entry_dict: Score entry containing the selected score and resolution.
+        score_type: Score column to process.
+        work_dir: Directory for generated plot output.
+        score_dir: Directory containing the default score CSV.
+        plot_name: Plot filename used when a bar plot is generated.
+        update_bin_file: Optional CSV used to update the resolution-bin size.
+
+    Returns:
+        tuple: Whole-dataset statistics, relative-resolution statistics, and bin size.
+
+    Raises:
+        ValueError: If no usable score CSV is available.
+    """
     if update_bin_file and os.path.isfile(update_bin_file):
         input_file = update_bin_file
     else:
@@ -391,6 +409,11 @@ def score_whole(new_entry, df, score_type='qscore'):
 
 
 def score_relative(new_entry, df, score_type='qscore', column='resolution', bin=0.5):
+    """Calculate a score percentile within a resolution range.
+
+    Returns:
+        tuple: Relative percentile and number of rows in the selected range.
+    """
     df_relative = get_resolution_range(new_entry, df, score_type, column, bin)
     if df_relative.empty:  # Handle case where df_relative is empty
         return 0., 0.  # Return NaN for q_relative and an empty list for row_indices
@@ -401,10 +424,16 @@ def score_relative(new_entry, df, score_type='qscore', column='resolution', bin=
     return q_relative, rows
 
 def score_relative_wrapper(args):
+    """Unpack arguments for parallel relative-score calculation."""
     x, df, score_type, column, bin = args
     return score_relative(x, df, score_type, column, bin)
 
 def fast_qscore_resolution_bin(df_resolution_sorted, score_type='qscore'):
+    """Add relative-score columns for a series of resolution-bin sizes.
+
+    Returns:
+        pandas.DataFrame: The input DataFrame with calculated relative-score columns.
+    """
     values = [round(x, 1) for x in np.arange(0.1, 1.6, 0.1)]
     for value in values:
         args_list = [
@@ -417,6 +446,11 @@ def fast_qscore_resolution_bin(df_resolution_sorted, score_type='qscore'):
     return df_resolution_sorted
 
 def find_optimal_correlation_index(arr):
+    """Return the index of the value closest to -0.3 among eligible values.
+
+    Returns:
+        int or None: Selected index, or ``None`` if no value exceeds -0.3.
+    """
     arr = np.asarray(arr)
     mask = arr > -0.3
     if not np.any(mask):
@@ -426,6 +460,11 @@ def find_optimal_correlation_index(arr):
     return np.where(arr == closest_value)[0][0]
 
 def resolution_qrelative_correlation(df_resolution_sorted, values, score_type='qscore'):
+    """Calculate correlations between resolution and relative-score columns.
+
+    Returns:
+        tuple: Correlations below 5, correlations above 5, and column names.
+    """
     correlation_below_5 = []
     correlation_above_5 = []
     col_names = []
@@ -463,6 +502,7 @@ def resolution_qrelative_correlation(df_resolution_sorted, values, score_type='q
     return correlation_below_5, correlation_above_5, col_names
 
 def get_resolution_bin_size_fromva(score_file):
+    """Read a score CSV and return its recorded resolution-bin mode."""
     df = pd.read_csv(score_file, dtype={'id': str, 'resolution': float, 'name': str, 'qscore': float}, usecols=[0, 1, 2, 3])
     df = df.dropna()
     df_resolution_sorted = df.sort_values(by='resolution')

{emdbva-0.0.1.dev139 → emdbva-0.0.1.dev143}/va/metrics/connected_percentage.py

@@ -1,12 +1,34 @@
+"""Measure connected and removed regions in thresholded MRC volumes."""
+
 import numpy as np
 import mrcfile
 from scipy.ndimage import label, find_objects
 
 
 def estimate_diameter_bbox(coords_physical):
+    """Estimate a point set's diameter from its axis-aligned bounding box.
+
+    Args:
+        coords_physical: Array of physical-space coordinates.
+
+    Returns:
+        float: Euclidean distance between opposite bounding-box corners.
+    """
     return np.linalg.norm(coords_physical.max(axis=0) - coords_physical.min(axis=0))
 
 def detect_small_blobs(volume, threshold, min_diameter, voxel_size=1.0, connectivity=2):
+    """Keep thresholded connected regions whose bounding-box diameter is large enough.
+
+    Args:
+        volume: Three-dimensional volume array.
+        threshold: Value used to create the binary foreground mask.
+        min_diameter: Minimum physical diameter to retain.
+        voxel_size: Physical size of one voxel.
+        connectivity: Connectivity mode used for labeling.
+
+    Returns:
+        tuple: Cleaned boolean mask and the number of removed voxels.
+    """
     binary = volume > threshold
     structure = np.ones((3, 3, 3)) if connectivity == 3 else None
     labeled, _ = label(binary, structure=structure)
@@ -26,6 +48,14 @@ def detect_small_blobs(volume, threshold, min_diameter, voxel_size=1.0, connecti
     return cleaned, total_removed_voxels
 
 def compute_connected_metrics(mrc_path, threshold, min_diameter=5.0, voxel_size=None, connectivity=2):
+    """Calculate connected and disconnected volume percentages from an MRC file.
+
+    The MRC volume is read from ``mrc_path``; the returned metrics are calculated
+    after removing regions below the requested diameter.
+
+    Returns:
+        dict: Connected and disconnected percentages and volumes.
+    """
     with mrcfile.open(mrc_path, permissive=True) as mrc:
         volume = mrc.data.copy()
         if voxel_size is None:

{emdbva-0.0.1.dev139 → emdbva-0.0.1.dev143}/va/metrics/contour_level_predicator.py

@@ -1,3 +1,5 @@
+"""Predict contour levels from normalized three-dimensional map volumes."""
+
 import os
 os.environ['KMP_DUPLICATE_LIB_OK'] = 'True'
 import torch
@@ -14,7 +16,10 @@ warnings.filterwarnings("ignore", message="User provided device_type of 'cuda',
 
 # Convolutional layers adapted from https://www.nature.com/articles/s41598-022-19212-6
 class CNNModel(nn.Module):
+    """Three-dimensional convolutional model used for contour prediction."""
+
     def __init__(self):
+        """Initialize the convolutional and fully connected layers."""
         super(CNNModel, self).__init__()
         self.conv = nn.Sequential(
             nn.Conv3d(1, 32, 7, 1, padding_mode='replicate'),
@@ -42,6 +47,7 @@ class CNNModel(nn.Module):
                                  nn.Linear(in_features=64, out_features=1))
 
     def forward(self, x):
+        """Run a forward pass on a batch of 64-by-64-by-64 volumes."""
         x = x.view(-1, 1, 64, 64, 64)
         x = self.conv(x)
         x = x.view(x.size(0), -1)
@@ -50,10 +56,19 @@ class CNNModel(nn.Module):
 
 
 def check_boxsize(vol):
+    """Return the first dimension of a volume array."""
     return vol.shape[0]
 
 
 def load_data(vol_d_norm):
+    """Wrap a normalized volume in a single-item PyTorch data loader.
+
+    Args:
+        vol_d_norm: Normalized three-dimensional volume.
+
+    Returns:
+        DataLoader: Single-item loader for model prediction.
+    """
     vol_array = np.empty(shape=(1, 64, 64, 64), dtype=np.float32)
     vol_array[:] = vol_d_norm
     data_generator = torch.utils.data.DataLoader(vol_array, batch_size=1, shuffle=False)
@@ -61,6 +76,7 @@ def load_data(vol_d_norm):
 
 
 def downsample(vol):
+    """Downsample a volume to 64 cubed voxels in Fourier space."""
     boxsize = check_boxsize(vol)
     vol_ft = np.fft.fftshift(np.fft.fftn(np.fft.fftshift(vol)))
     start = boxsize // 2 - 64 // 2
@@ -75,6 +91,7 @@ def downsample(vol):
 
 def upsample(
         vol):  # through interpolation of maps in Fourier space; based on https://www.sciencedirect.com/science/article/pii/S001046551400335X
+    """Pad a volume in Fourier space to the model's 64 cubed input size."""
     boxsize = check_boxsize(vol)
     new_box_size = 64
     vol_ft = np.fft.fftshift(np.fft.fftn(np.fft.fftshift(vol)))
@@ -87,6 +104,11 @@ def upsample(
 
 
 def normalize(vol_data):
+    """Clip and normalize positive volume values for model input.
+
+    Returns:
+        tuple: Normalized volume and the lower and upper scaling values.
+    """
     d_upper = np.percentile(vol_data, 99.999)
     d_lower = np.percentile(vol_data, 0.001)
     vol_data = np.where(vol_data > d_upper, d_upper, vol_data)
@@ -109,6 +131,14 @@ model.load_state_dict(checkpoint['model_state_dict'])
 
 
 def model_pred(data_generator):
+    """Run the loaded model over a data loader without gradient tracking.
+
+    Args:
+        data_generator: Data loader containing normalized volume batches.
+
+    Returns:
+        list: Model prediction tensors collected for each batch.
+    """
     model.eval()
     pred_list = []
     with torch.no_grad():
@@ -122,6 +152,14 @@ def model_pred(data_generator):
 
 
 def calc_level_dev(vol_data):
+    """Predict contour levels after resizing the volume to model dimensions.
+
+    Args:
+        vol_data: Three-dimensional volume array.
+
+    Returns:
+        numpy.ndarray: Predicted contour-level values rescaled to input units.
+    """
     boxsize = check_boxsize(vol_data)
 
     if boxsize > 64:
@@ -154,4 +192,3 @@ def calc_level_dev(vol_data):
 
 
 
-

{emdbva-0.0.1.dev139 → emdbva-0.0.1.dev143}/va/metrics/map_data_validation.py

@@ -59,13 +59,127 @@ def _to_float(value):
 
 
 def _parse_validation_line(line, source="mrcfile.validate"):
-    """
-    Parse one line from mrcfile.validate() or one RuntimeWarning.
 
-    Any message not recognised by the parser is still kept in the JSON as
-    "unclassified_mrcfile_validation_message" so future mrcfile versions do
-    not silently lose information.
     """
+    Parse one line from ``mrcfile.validate()`` output or one captured
+    ``RuntimeWarning`` into a structured validation issue.
+    The returned issue is created by ``_make_issue()`` and contains:
+        code
+            Stable machine-readable issue code.
+        category
+            Header/data/file area affected by the issue.
+        severity
+            Local VA severity assigned to the issue. This is intentionally
+            not always identical to the strict ``mrcfile.validate()`` result.
+            VA uses the parsed severity to decide its own pipeline-level
+            validity.
+        source
+            Message source, usually ``"mrcfile.validate"`` or
+            ``"RuntimeWarning"``.
+        message
+            Original mrcfile message, preserved verbatim for debugging.
+        details
+            Parsed values extracted from the message, such as header field
+            names, expected values, actual values, byte counts, or exception
+            information.
+    Severity mapping used by this parser:
+        map_id_incorrect
+            warning
+            The MAP ID header string differs from the expected value.
+        map_id_missing_or_corrupt
+            warning
+            The MAP ID string is absent, suggesting the file may not be an
+            MRC file or may be corrupt.
+        machine_stamp_invalid
+            error
+            The machine stamp is invalid.
+        machine_stamp_byte_order_mismatch
+            warning
+            The machine stamp does not match the apparent byte order.
+        mode_invalid
+            error
+            The MRC mode value is invalid.
+        mode_unrecognised_data_unreadable
+            error
+            The MRC mode is unrecognised and the data block cannot be read.
+        header_field_negative
+            error
+            A non-negative integer header field such as nx, ny, nz, mx, my,
+            mz, ispg, or nlabl is negative.
+        cell_dimension_negative
+            error
+            One of the cell dimensions x, y, or z is negative.
+        axis_mapping_invalid
+            error
+            The map axis mapping is not the expected [1, 2, 3] permutation.
+        volume_stack_dimensions_invalid
+            error
+            For a volume stack, nz is not divisible by mz.
+        header_labels_empty_between_text
+            error
+            Empty labels appear between labels containing text.
+        header_labels_nlabl_mismatch
+            error
+            The nlabl header value does not match the number of non-empty
+            label records.
+        mrc_format_version_invalid
+            warning
+            The nversion field does not declare MRC2014 version 20140 or
+            20141.
+        extended_header_type_invalid
+            error
+            The extended-header type is undefined or unrecognised.
+        data_statistics_rms_mismatch
+            error
+            The calculated RMS deviation differs from the header value.
+        data_statistics_minimum_mismatch
+            error
+            The calculated minimum differs from the header value.
+        data_statistics_maximum_mismatch
+            error
+            The calculated maximum differs from the header value.
+        data_statistics_mean_mismatch
+            error
+            The calculated mean differs from the header value.
+        file_size_larger_than_expected
+            error
+            The physical file size is larger than the size calculated from
+            the header.
+        data_block_unreadable_file_size_not_checked
+            error
+            The data block could not be read, so file size could not be
+            checked.
+        extended_header_too_small
+            error
+            The file contains fewer extended-header bytes than expected.
+        data_block_too_small
+            error
+            The file contains fewer data-block bytes than expected.
+        data_block_exceeds_read_limit
+            error
+            The expected data block exceeds the configured read limit.
+        mrc_header_too_small
+            error
+            The file does not contain enough bytes for a full MRC header.
+        exception_during_validation
+            error
+            A Python exception-like message was emitted during validation.
+        unclassified_mrcfile_validation_message
+            warning
+            Fallback for any unrecognised message. The original message is
+            still preserved so new mrcfile messages are not silently lost.
+    Notes
+    -----
+    Some messages that ``mrcfile.validate()`` treats as validation failures
+    are intentionally classified as ``warning`` here, for example
+    ``map_id_incorrect`` and ``mrc_format_version_invalid``. This lets VA
+    distinguish strict mrcfile validity from VA's own pipeline-level
+    acceptability.
+    Unknown messages are kept as
+    ``unclassified_mrcfile_validation_message`` instead of being discarded.
+    This makes the parser forward-compatible with future mrcfile output.
+    """
+
     line = line.strip()
 
     # 1. MRC map ID/header map field
@@ -552,6 +666,9 @@ def _parse_messages_and_warnings(messages_text, warning_messages):
 
 
 def validate_single_map(map_input):
+    """
+    Validate a single map file using mrcfile.validate() and capture any warnings.
+    """
     map_path = Path(_normalise_map_input(map_input))
     messages = io.StringIO()
     warning_messages = []
@@ -559,7 +676,7 @@ def validate_single_map(map_input):
     result = OrderedDict([
         ("file", str(map_path)),
         ("exists", map_path.exists()),
-        ("valid", False),
+        ("no_known_critical_error", False),
 
         # New structured fields
         ("issue_count", 0),

{emdbva-0.0.1.dev139 → emdbva-0.0.1.dev143}/va/metrics/phaserandomization.py

@@ -1,3 +1,5 @@
+"""Create RELION masks and FSC inputs from map volumes."""
+
 from va.utils.ChimeraxViews import *
 from va.utils.misc import find_rawmap_file
 import numpy as np
@@ -57,6 +59,14 @@ def check_mrc(input_map):
 
 @profile_peak_memory()
 def relion_mask(raw_map, out_dir, mapname=None):
+    """Create a RELION mask and a locally generated comparison mask.
+
+    The function invokes the RELION mask executable when available and writes
+    the resulting mask into ``out_dir``.
+
+    Returns:
+        str or None: Generated mask path when successful.
+    """
     relion_mask_executable_name = 'relion_mask_create'
     relion_mask_executable = find_executable(relion_mask_executable_name)
     if relion_mask_executable:
@@ -140,7 +150,9 @@ def relion_fsc(mapone, maptwo, mask_file=None, out_dir=None):
 def relion_fsc_calculation(mapone, maptwo, root, mapname=None):
     """
         Calculates FSc using Relion
-    return: data dictionary of fsc
+
+    Returns:
+        dict: Data dictionary containing the FSC result.
     """
 
     result_type = 'fsc'
@@ -166,6 +178,7 @@ def relion_fsc_calculation(mapone, maptwo, root, mapname=None):
         return None
 
 def get_voxel_size(input_map):
+    """Return the x-axis voxel size read from an MRC map."""
 
     try:
         with mrcfile.open(input_map, permissive=True) as mrc:
@@ -193,6 +206,18 @@ def calculate_pixels(angpix):
 
 # following is the Python version of Relion auto masking
 def relion_auto_mask_fast(data, threshold, extend_pixels, edge_width, verbose=True):
+    """Build a soft-edged binary mask from an in-memory volume array.
+
+    Args:
+        data: Volume array to threshold.
+        threshold: Initial density threshold.
+        extend_pixels: Number of pixels to extend or shrink the mask.
+        edge_width: Width of the soft edge in pixels.
+        verbose: Whether to display progress messages.
+
+    Returns:
+        numpy.ndarray: Floating-point mask array.
+    """
     steps = []
     if verbose:
         steps = tqdm(total=3, desc="Masking Steps", unit="step")
@@ -239,6 +264,10 @@ def relion_auto_mask_fast(data, threshold, extend_pixels, edge_width, verbose=Tr
 
 @profile_peak_memory()
 def relion_auto_mask(input_file, output_file, threshold, extend_pixels, edge_width, verbose=True):
+    """Create an MRC mask file from an input MRC volume.
+
+    The input voxel size is copied to the output file.
+    """
     with mrcfile.open(input_file) as mrc:
         data = mrc.data.copy()
         voxel_size = mrc.voxel_size.copy()
@@ -251,4 +280,3 @@ def relion_auto_mask(input_file, output_file, threshold, extend_pixels, edge_wid
 
     if verbose:
         print(f"== Mask saved to {output_file} ==")
-