utils

formatting

chapter(title)

Formats a chapter header with bold magenta text, uppercase, and padding.

Source code in src/easydiffraction/utils/formatting.py

def chapter(title: str) -> str:
    """Formats a chapter header with bold magenta text, uppercase, and padding."""
    full_title = f' {title.upper()} '
    pad_len = (WIDTH - len(full_title)) // 2
    padding = SYMBOL * pad_len
    line = f'{Fore.LIGHTMAGENTA_EX + Style.BRIGHT}{padding}{full_title}{padding}{Style.RESET_ALL}'
    if len(line) < WIDTH:
        line += SYMBOL
    return f'\n{line}'

error(title)

Formats an error message with red text.

Source code in src/easydiffraction/utils/formatting.py

def error(title: str) -> str:
    """Formats an error message with red text."""
    return f'\n❌ {Fore.LIGHTRED_EX}Error{Style.RESET_ALL}\n{title}'

info(title)

Formats an info message with cyan text.

Source code in src/easydiffraction/utils/formatting.py

def info(title: str) -> str:
    """Formats an info message with cyan text."""
    return f'\nℹ️ {Fore.LIGHTCYAN_EX}Info{Style.RESET_ALL}\n{title}'

paragraph(title)

Formats a subsection header with bold blue text while keeping quoted text unformatted.

Source code in src/easydiffraction/utils/formatting.py

def paragraph(title: str) -> str:
    """Formats a subsection header with bold blue text while keeping quoted text unformatted."""
    import re

    parts = re.split(r"('.*?')", title)
    formatted = f'{Fore.LIGHTBLUE_EX + Style.BRIGHT}'
    for part in parts:
        if part.startswith("'") and part.endswith("'"):
            formatted += Style.RESET_ALL + part + Fore.LIGHTBLUE_EX + Style.BRIGHT
        else:
            formatted += part
    formatted += Style.RESET_ALL
    return f'\n{formatted}'

section(title)

Formats a section header with bold green text.

Source code in src/easydiffraction/utils/formatting.py

def section(title: str) -> str:
    """Formats a section header with bold green text."""
    full_title = f'*** {title.upper()} ***'
    return f'\n{Fore.LIGHTGREEN_EX + Style.BRIGHT}{full_title}{Style.RESET_ALL}'

warning(title)

Formats a warning message with yellow text.

Source code in src/easydiffraction/utils/formatting.py

def warning(title: str) -> str:
    """Formats a warning message with yellow text."""
    return f'\n⚠️ {Fore.LIGHTYELLOW_EX}Warning{Style.RESET_ALL}\n{title}'

utils

General utilities and helpers for easydiffraction.

download_from_repository(file_name, branch=None, destination='data', overwrite=False)

Download a data file from the EasyDiffraction repository on GitHub.

Parameters:

Name	Type	Description	Default
file_name	str	The file name to fetch (e.g., "NaCl.gr").	required
branch	str | None	Branch to fetch from. If None, uses DATA_REPO_BRANCH.	None
destination	str	Directory to save the file into (created if missing).	'data'
overwrite	bool	Whether to overwrite the file if it already exists. Defaults to False.	False

Returns:

Type	Description
None	None

Source code in src/easydiffraction/utils/utils.py

def download_from_repository(
    file_name: str,
    branch: str | None = None,
    destination: str = 'data',
    overwrite: bool = False,
) -> None:
    """Download a data file from the EasyDiffraction repository on GitHub.

    Args:
        file_name: The file name to fetch (e.g., "NaCl.gr").
        branch: Branch to fetch from. If None, uses DATA_REPO_BRANCH.
        destination: Directory to save the file into (created if missing).
        overwrite: Whether to overwrite the file if it already exists. Defaults to False.

    Returns:
        None
    """
    file_path = os.path.join(destination, file_name)
    if os.path.exists(file_path):
        if not overwrite:
            print(warning(f"File '{file_path}' already exists and will not be overwritten."))
            return
        else:
            print(warning(f"File '{file_path}' already exists and will be overwritten."))
            os.remove(file_path)

    base = 'https://raw.githubusercontent.com'
    org = 'easyscience'
    repo = 'diffraction-lib'
    branch = branch or DATA_REPO_BRANCH  # Use the global branch variable if not provided
    path_in_repo = 'tutorials/data'
    url = f'{base}/{org}/{repo}/refs/heads/{branch}/{path_in_repo}/{file_name}'

    pooch.retrieve(
        url=url,
        known_hash=None,
        fname=file_name,
        path=destination,
    )

fetch_tutorial_list()

Return a list of available tutorial notebook filenames from the GitHub release that matches the installed version of easydiffraction, if possible. If the version-specific release is unavailable, falls back to the latest release.

This function does not fetch or display the tutorials themselves; it only lists the notebook filenames (e.g., '01-intro.ipynb', ...) found inside the 'tutorials.zip' asset of the appropriate GitHub release.

Returns:

Type	Description
list[str]	list[str]: A sorted list of tutorial notebook filenames (without directories)
list[str]	extracted from the corresponding release's tutorials.zip, or an empty list
list[str]	if unavailable.

Source code in src/easydiffraction/utils/utils.py

def fetch_tutorial_list() -> list[str]:
    """
    Return a list of available tutorial notebook filenames from the GitHub release
    that matches the installed version of `easydiffraction`, if possible. If the
    version-specific release is unavailable, falls back to the latest release.

    This function does not fetch or display the tutorials themselves; it only lists
    the notebook filenames (e.g., '01-intro.ipynb', ...) found inside the
    'tutorials.zip' asset of the appropriate GitHub release.

    Returns:
        list[str]: A sorted list of tutorial notebook filenames (without directories)
        extracted from the corresponding release's tutorials.zip, or an empty list
        if unavailable.
    """
    version_str = stripped_package_version('easydiffraction')
    tag = f'v{version_str}' if version_str is not None else None
    release_info = _get_release_info(tag)
    # Fallback to latest if tag fetch failed and tag was attempted
    if release_info is None and tag is not None:
        print(error('Falling back to latest release info...'))
        release_info = _get_release_info(None)
    if release_info is None:
        return []
    tutorial_asset = _get_tutorial_asset(release_info)
    if not tutorial_asset:
        print(error("'tutorials.zip' not found in the release."))
        return []
    download_url = tutorial_asset.get('browser_download_url')
    if not download_url:
        print(error("'browser_download_url' not found for tutorials.zip."))
        return []
    return _extract_notebooks_from_asset(download_url)

fetch_tutorials()

Download and extract the tutorials ZIP archive from the GitHub release matching the installed version of easydiffraction, if available. If the version-specific release is unavailable, falls back to the latest release.

The archive is extracted into the current working directory and then removed.

Returns:

Type	Description
None	None

Source code in src/easydiffraction/utils/utils.py

def fetch_tutorials() -> None:
    """
    Download and extract the tutorials ZIP archive from the GitHub release matching the
    installed version of `easydiffraction`, if available. If the version-specific release
    is unavailable, falls back to the latest release.

    The archive is extracted into the current working directory and then removed.

    Args:
        None

    Returns:
        None
    """
    version_str = stripped_package_version('easydiffraction')
    tag = f'v{version_str}' if version_str is not None else None
    release_info = _get_release_info(tag)
    # Fallback to latest if tag fetch failed and tag was attempted
    if release_info is None and tag is not None:
        print(error('Falling back to latest release info...'))
        release_info = _get_release_info(None)
    if release_info is None:
        print(error('Unable to fetch release info.'))
        return
    tutorial_asset = _get_tutorial_asset(release_info)
    if not tutorial_asset:
        print(error("'tutorials.zip' not found in the release."))
        return
    file_url = tutorial_asset.get('browser_download_url')
    if not file_url:
        print(error("'browser_download_url' not found for tutorials.zip."))
        return
    file_name = 'tutorials.zip'
    # Validate URL for security
    _validate_url(file_url)

    print('📥 Downloading tutorial notebooks...')
    urllib.request.urlretrieve(file_url, file_name)  # noqa: S310

    print('📦 Extracting tutorials to "tutorials/"...')
    with zipfile.ZipFile(file_name, 'r') as zip_ref:
        zip_ref.extractall()

    print('🧹 Cleaning up...')
    os.remove(file_name)

    print('✅ Tutorials fetched successfully.')

get_value_from_xye_header(file_path, key)

Extracts a floating point value from the first line of the file, corresponding to the given key.

Parameters:

Name	Type	Description	Default
file_path	str	Path to the input file.	required
key	str	The key to extract ('DIFC' or 'two_theta').	required

Returns:

Name	Type	Description
float		The extracted value.

Raises:

Type	Description
ValueError	If the key is not found.

Source code in src/easydiffraction/utils/utils.py

def get_value_from_xye_header(file_path, key):
    """
    Extracts a floating point value from the first line of the file, corresponding to the given key.

    Parameters:
        file_path (str): Path to the input file.
        key (str): The key to extract ('DIFC' or 'two_theta').

    Returns:
        float: The extracted value.

    Raises:
        ValueError: If the key is not found.
    """
    pattern = rf'{key}\s*=\s*([-+]?[0-9]*\.?[0-9]+([eE][-+]?[0-9]+)?)'

    with open(file_path, 'r') as f:
        first_line = f.readline()

    match = re.search(pattern, first_line)
    if match:
        return float(match.group(1))
    else:
        raise ValueError(f'{key} not found in the header.')

is_colab()

Determines if the current environment is Google Colab.

Returns:

Name	Type	Description
bool	bool	True if running in Google Colab PyCharm, False otherwise.

Source code in src/easydiffraction/utils/utils.py

def is_colab() -> bool:
    """
    Determines if the current environment is Google Colab.

    Returns:
        bool: True if running in Google Colab PyCharm, False otherwise.
    """
    try:
        return importlib.util.find_spec('google.colab') is not None
    except ModuleNotFoundError:
        return False

is_github_ci()

Determines if the current process is running in GitHub Actions CI.

Returns:

Name	Type	Description
bool	bool	True if the environment variable GITHUB_ACTIONS is set
	bool	(Always "true" on GitHub Actions), False otherwise.

Source code in src/easydiffraction/utils/utils.py

def is_github_ci() -> bool:
    """
    Determines if the current process is running in GitHub Actions CI.

    Returns:
        bool: True if the environment variable ``GITHUB_ACTIONS`` is set
        (Always "true" on GitHub Actions), False otherwise.
    """
    return os.environ.get('GITHUB_ACTIONS') is not None

is_notebook()

Determines if the current environment is a Jupyter Notebook.

Returns:

Name	Type	Description
bool	bool	True if running inside a Jupyter Notebook, False otherwise.

Source code in src/easydiffraction/utils/utils.py

def is_notebook() -> bool:
    """
    Determines if the current environment is a Jupyter Notebook.

    Returns:
        bool: True if running inside a Jupyter Notebook, False otherwise.
    """
    if IPython is None:
        return False
    if is_pycharm():  # Running inside PyCharm
        return False
    if is_colab():  # Running inside Google Colab
        return True

    try:
        shell = get_ipython().__class__.__name__  # noqa: F821
        if shell == 'ZMQInteractiveShell':  # Jupyter notebook or qtconsole
            return True
        elif shell == 'TerminalInteractiveShell':  # Terminal running IPython
            return False
        else:  # Other type (unlikely)
            return False
    except NameError:
        return False  # Probably standard Python interpreter

is_pycharm()

Determines if the current environment is PyCharm.

Returns:

Name	Type	Description
bool	bool	True if running inside PyCharm, False otherwise.

Source code in src/easydiffraction/utils/utils.py

def is_pycharm() -> bool:
    """
    Determines if the current environment is PyCharm.

    Returns:
        bool: True if running inside PyCharm, False otherwise.
    """
    return os.environ.get('PYCHARM_HOSTED') == '1'

list_tutorials()

List available tutorial notebooks.

Returns:

Type	Description
	None

Source code in src/easydiffraction/utils/utils.py

def list_tutorials():
    """
    List available tutorial notebooks.

    Args:
        None

    Returns:
        None
    """
    tutorials = fetch_tutorial_list()
    columns_data = [[t] for t in tutorials]
    columns_alignment = ['left']

    released_ed_version = stripped_package_version('easydiffraction')

    print(paragraph(f'📘 Tutorials available for easydiffraction v{released_ed_version}:'))
    render_table(
        columns_data=columns_data,
        columns_alignment=columns_alignment,
        show_index=True,
    )

package_version(package_name)

Get the installed version string of the specified package.

Parameters:

Name	Type	Description	Default
package_name	str	The name of the package to query.	required

Returns:

Type	Description
str | None	str | None: The raw version string (may include local part, e.g., '1.2.3+abc123'),
str | None	or None if the package is not installed.

Source code in src/easydiffraction/utils/utils.py

def package_version(package_name: str) -> str | None:
    """
    Get the installed version string of the specified package.

    Args:
        package_name (str): The name of the package to query.

    Returns:
        str | None: The raw version string (may include local part, e.g., '1.2.3+abc123'),
        or None if the package is not installed.
    """
    try:
        return version(package_name)
    except PackageNotFoundError:
        return None

render_cif(cif_text, paragraph_title)

Display the CIF text as a formatted table in Jupyter Notebook or terminal.

Parameters:

Name	Type	Description	Default
cif_text		The CIF text to display.	required
paragraph_title		The title to print above the table.	required

Returns:

Type	Description
None	None

Source code in src/easydiffraction/utils/utils.py

def render_cif(cif_text, paragraph_title) -> None:
    """
    Display the CIF text as a formatted table in Jupyter Notebook or terminal.

    Args:
        cif_text: The CIF text to display.
        paragraph_title: The title to print above the table.

    Returns:
        None
    """
    # Split into lines and replace empty ones with a ' '
    # (non-breaking space) to force empty lines to be rendered in
    # full height in the table. This is only needed in Jupyter Notebook.
    if is_notebook():
        lines: List[str] = [line if line.strip() else ' ' for line in cif_text.splitlines()]
    else:
        lines: List[str] = [line for line in cif_text.splitlines()]

    # Convert each line into a single-column format for table rendering
    columns: List[List[str]] = [[line] for line in lines]

    # Print title paragraph
    print(paragraph_title)

    # Render the table using left alignment and no headers
    render_table(
        columns_data=columns,
        columns_alignment=['left'],
    )

render_table(columns_data, columns_alignment, columns_headers=None, show_index=False, display_handle=None)

Renders a table either as an HTML (in Jupyter Notebook) or ASCII (in terminal), with aligned columns.

Parameters:

Name	Type	Description	Default
columns_data	list	List of lists, where each inner list represents a row of data.	required
columns_alignment	list	Corresponding text alignment for each column (e.g., 'left', 'center', 'right').	required
columns_headers	list	List of column headers.	None
show_index	bool	Whether to show the index column.	False
display_handle		Optional display handle for updating in Jupyter.	None

Returns:

Type	Description
	None

Source code in src/easydiffraction/utils/utils.py

def render_table(
    columns_data,
    columns_alignment,
    columns_headers=None,
    show_index=False,
    display_handle=None,
):
    """
    Renders a table either as an HTML (in Jupyter Notebook) or ASCII (in terminal),
    with aligned columns.

    Args:
        columns_data (list): List of lists, where each inner list represents a row of data.
        columns_alignment (list): Corresponding text alignment for each column (e.g., 'left', 'center', 'right').
        columns_headers (list): List of column headers.
        show_index (bool): Whether to show the index column.
        display_handle: Optional display handle for updating in Jupyter.

    Returns:
        None
    """

    # Use pandas DataFrame for Jupyter Notebook rendering
    if is_notebook():
        # Create DataFrame
        if columns_headers is None:
            df = pd.DataFrame(columns_data)
            df.columns = range(df.shape[1])  # Ensure numeric column labels
            columns_headers = df.columns.tolist()
            skip_headers = True
        else:
            df = pd.DataFrame(columns_data, columns=columns_headers)
            skip_headers = False

        # Force starting index from 1
        if show_index:
            df.index += 1

        # Replace None/NaN values with empty strings
        df.fillna('', inplace=True)

        # Formatters for data cell alignment and replacing None with empty string
        def make_formatter(align):
            return lambda x: f'<div style="text-align: {align};">{x}</div>'

        formatters = {col: make_formatter(align) for col, align in zip(columns_headers, columns_alignment)}

        # Convert DataFrame to HTML
        html = df.to_html(
            escape=False,
            index=show_index,
            formatters=formatters,
            border=0,
            header=not skip_headers,
        )

        # Add inline CSS to align the entire table to the left and show border
        html = html.replace(
            '<table class="dataframe">',
            '<table class="dataframe" '
            'style="'
            'border-collapse: collapse; '
            'border: 1px solid #515155; '
            'margin-left: 0.5em;'
            'margin-top: 0.5em;'
            'margin-bottom: 1em;'
            '">',
        )

        # Manually apply text alignment to headers
        if not skip_headers:
            for col, align in zip(columns_headers, columns_alignment):
                html = html.replace(f'<th>{col}', f'<th style="text-align: {align};">{col}')

        # Display or update the table in Jupyter Notebook
        if display_handle is not None:
            display_handle.update(HTML(html))
        else:
            display(HTML(html))

    # Use tabulate for terminal rendering
    else:
        if columns_headers is None:
            columns_headers = []

        indices = show_index
        if show_index:
            # Force starting index from 1
            indices = range(1, len(columns_data) + 1)

        table = tabulate(
            columns_data,
            headers=columns_headers,
            tablefmt='fancy_outline',
            numalign='left',
            stralign='left',
            showindex=indices,
        )

        print(table)

show_version()

Print the installed version of the easydiffraction package.

Returns:

Type	Description
None	None

Source code in src/easydiffraction/utils/utils.py

def show_version() -> None:
    """
    Print the installed version of the easydiffraction package.

    Args:
        None

    Returns:
        None
    """
    current_ed_version = package_version('easydiffraction')
    print(paragraph(f'📘 Current easydiffraction v{current_ed_version}'))

stripped_package_version(package_name)

Get the installed version of the specified package, stripped of any local version part.

Returns only the public version segment (e.g., '1.2.3' or '1.2.3.post4'), omitting any local segment (e.g., '+d136').

Parameters:

Name	Type	Description	Default
package_name	str	The name of the package to query.	required

Returns:

Type	Description
str | None	str | None: The public version string, or None if the package is not installed.

Source code in src/easydiffraction/utils/utils.py

def stripped_package_version(package_name: str) -> str | None:
    """
    Get the installed version of the specified package, stripped of any local version part.

    Returns only the public version segment (e.g., '1.2.3' or '1.2.3.post4'),
    omitting any local segment (e.g., '+d136').

    Args:
        package_name (str): The name of the package to query.

    Returns:
        str | None: The public version string, or None if the package is not installed.
    """
    v_str = package_version(package_name)
    if v_str is None:
        return None
    try:
        v = Version(v_str)
        return str(v.public)
    except Exception:
        return v_str

tof_to_d(tof, offset, linear, quad, quad_eps=1e-20)

Convert time-of-flight (TOF) to d-spacing using a quadratic calibration.

Model

TOF = offset + linear * d + quad * d²

The function

• Uses a linear fallback when the quadratic term is effectively zero.
• Solves the quadratic for d and selects the smallest positive, finite root.
• Returns NaN where no valid solution exists.
• Expects tof as a NumPy array; output matches its shape.

Parameters:

Name	Type	Description	Default
tof	ndarray	Time-of-flight values (µs). Must be a NumPy array.	required
offset	float	Calibration offset (µs).	required
linear	float	Linear calibration coefficient (µs/Å).	required
quad	float	Quadratic calibration coefficient (µs/Ų).	required
quad_eps	float	Threshold to treat quad as zero. Defaults to 1e-20.	1e-20

Returns:

Type	Description
ndarray	np.ndarray: d-spacing values (Å), NaN where invalid.

Raises:

Type	Description
TypeError	If tof is not a NumPy array or coefficients are not real numbers.

Source code in src/easydiffraction/utils/utils.py

def tof_to_d(
    tof: np.ndarray,
    offset: float,
    linear: float,
    quad: float,
    quad_eps=1e-20,
) -> np.ndarray:
    """Convert time-of-flight (TOF) to d-spacing using a quadratic calibration.

    Model:
        TOF = offset + linear * d + quad * d²

    The function:
      - Uses a linear fallback when the quadratic term is effectively zero.
      - Solves the quadratic for d and selects the smallest positive, finite root.
      - Returns NaN where no valid solution exists.
      - Expects ``tof`` as a NumPy array; output matches its shape.

    Args:
        tof (np.ndarray): Time-of-flight values (µs). Must be a NumPy array.
        offset (float): Calibration offset (µs).
        linear (float): Linear calibration coefficient (µs/Å).
        quad (float): Quadratic calibration coefficient (µs/Ų).
        quad_eps (float, optional): Threshold to treat ``quad`` as zero. Defaults to 1e-20.

    Returns:
        np.ndarray: d-spacing values (Å), NaN where invalid.

    Raises:
        TypeError: If ``tof`` is not a NumPy array or coefficients are not real numbers.
    """
    # Type checks
    if not isinstance(tof, np.ndarray):
        raise TypeError(f"'tof' must be a NumPy array, got {type(tof).__name__}")
    for name, val in (('offset', offset), ('linear', linear), ('quad', quad), ('quad_eps', quad_eps)):
        if not isinstance(val, (int, float, np.integer, np.floating)):
            raise TypeError(f"'{name}' must be a real number, got {type(val).__name__}")

    # Output initialized to NaN
    d_out = np.full_like(tof, np.nan, dtype=float)

    # 1) If quadratic term is effectively zero, use linear formula:
    #    TOF ≈ offset + linear * d =>
    #    d ≈ (tof - offset) / linear
    if abs(quad) < quad_eps:
        if linear != 0.0:
            d = (tof - offset) / linear
            # Keep only positive, finite results
            valid = np.isfinite(d) & (d > 0)
            d_out[valid] = d[valid]
        # If B == 0 too, there's no solution; leave NaN
        return d_out

    # 2) If quadratic term is significant, solve the quadratic equation:
    #    TOF = offset + linear * d + quad * d² =>
    #    quad * d² + linear * d + (offset - tof) = 0
    discr = linear**2 - 4 * quad * (offset - tof)
    has_real_roots = discr >= 0

    if np.any(has_real_roots):
        sqrt_discr = np.sqrt(discr[has_real_roots])

        root_1 = (-linear + sqrt_discr) / (2 * quad)
        root_2 = (-linear - sqrt_discr) / (2 * quad)

        # Pick smallest positive, finite root per element
        roots = np.stack((root_1, root_2), axis=0)  # Stack roots for comparison
        roots = np.where(np.isfinite(roots) & (roots > 0), roots, np.nan)  # Replace non-finite or negative roots with NaN
        chosen = np.nanmin(roots, axis=0)  # Choose the smallest positive root or NaN if none are valid

        d_out[has_real_roots] = chosen

    return d_out

twotheta_to_d(twotheta, wavelength)

Convert 2-theta to d-spacing using Bragg's law.

Parameters:

Name	Type	Description	Default
twotheta	float or ndarray	2-theta angle in degrees.	required
wavelength	float	Wavelength in Å.	required

Returns:

Name	Type	Description
d	float or ndarray	d-spacing in Å.

Source code in src/easydiffraction/utils/utils.py

def twotheta_to_d(twotheta, wavelength):
    """
    Convert 2-theta to d-spacing using Bragg's law.

    Parameters:
        twotheta (float or np.ndarray): 2-theta angle in degrees.
        wavelength (float): Wavelength in Å.

    Returns:
        d (float or np.ndarray): d-spacing in Å.
    """
    # Convert twotheta from degrees to radians
    theta_rad = np.radians(twotheta / 2)

    # Calculate d-spacing using Bragg's law
    d = wavelength / (2 * np.sin(theta_rad))

    return d