kwneuro.files
=============

.. py:module:: kwneuro.files

.. autoapi-nested-parse::

   User-facing file-first helpers that adapt paths to kwneuro resources.

   This module is a convenience layer for scripts, notebooks, and CLI-style
   workflows. The internal on-disk resource implementations live in
   ``kwneuro.io``.



Functions
---------

.. autoapisummary::

   kwneuro.files.read_volume
   kwneuro.files.write_volume
   kwneuro.files.read_dwi_fsl
   kwneuro.files.write_dwi_fsl
   kwneuro.files.read_structural
   kwneuro.files.write_structural


Module Contents
---------------

.. py:function:: read_volume(path: kwneuro.util.PathLike) -> kwneuro.io.NiftiVolumeResource

   Create a lazy volume resource from a NIfTI path.


.. py:function:: write_volume(volume: kwneuro.resource.VolumeResource, path: kwneuro.util.PathLike) -> kwneuro.io.NiftiVolumeResource

   Write a volume resource to a NIfTI path and return the on-disk resource.


.. py:function:: read_dwi_fsl(volume: kwneuro.util.PathLike, bval: kwneuro.util.PathLike | None = None, bvec: kwneuro.util.PathLike | None = None) -> kwneuro.dwi.Dwi

   Create a DWI from a NIfTI volume and FSL b-value/b-vector files.

   When ``bval`` or ``bvec`` are omitted, they are inferred from the DWI volume
   path by replacing a ``.nii`` or ``.nii.gz`` suffix with ``.bval`` and
   ``.bvec``. This covers common BIDS-style DWI sidecars when the NIfTI path is
   passed directly.


.. py:function:: write_dwi_fsl(dwi: kwneuro.dwi.Dwi, volume: kwneuro.util.PathLike, bval: kwneuro.util.PathLike | None = None, bvec: kwneuro.util.PathLike | None = None) -> kwneuro.dwi.Dwi

   Write a DWI to NIfTI plus FSL b-value/b-vector files.

   When ``bval`` or ``bvec`` are omitted, sidecar paths are inferred from the
   output volume path in the same way as :func:`read_dwi_fsl`.


.. py:function:: read_structural(path: kwneuro.util.PathLike) -> kwneuro.structural.StructuralImage

   Create a structural image from a lazy NIfTI volume resource.


.. py:function:: write_structural(structural: kwneuro.structural.StructuralImage, path: kwneuro.util.PathLike) -> kwneuro.structural.StructuralImage

   Write a structural image to a NIfTI path and return the on-disk image.