fix: missing documenation addition and inaccuracies fix

docs/raw_format.rst

@@ -28,33 +28,36 @@ MetaData
 Attributes
 +++++++++++
 
+acquisitionMode: str
+    Description of the type of acquisition (ex: 2Dscan, 3Dscan, ...)
+
 transmitFrequency : float
-    The transmit frequency of the acquisition
+    The transmit frequency of the acquisition, in MHz
 
 prf : float
-    The pulse repetition frequency
+    The pulse repetition frequency, Hz
 
 speedOfSound : float
-    The speed of sound
+    The speed of sound, in meter per second
 
 frameRate : float
-    Frame rate of the acquisition
+    Frame rate of the acquisition, in Hz
 
 receiveAperture : np.ndarray
-    Receive Aperture
+    Receive aperture, first and last elements of the aperture
 
 depth : Scan.Depth
-    Near and Far depth
+    Near and Far depth, in millimeter
 
 flatAngles : np.ndarray
-    Angles of the probe during the acquisition
+    Angles of the probe during the acquisition, in degrees
 
 voxDim : Scan.VoxDim
-    VoxDim data
+    Voxel dimension x, y and z, in meters
 
 blockDim : np.ndarray
-    BlockDim data
-
+    Block dimension x, y, z, angle, frame 
+    
 compound : bool
     True if the images are compounded, False otherwise
 
@@ -73,6 +76,3 @@ They are one-based and inclusive, and default to block 1. If ``blockEnd`` is
 greater than ``numberOfBlock``, it is clamped to the available number of
 blocks and a ``RuntimeWarning`` is emitted. ``blockEnd`` smaller than
 ``blockStart`` raises ``RuntimeError``.
-
-acquisitionMode : str
-    Type of acquisition

docs/roi_format.rst

@@ -26,7 +26,7 @@ Attributes
 name : str
     Name of the ROI
 
-color : tuple[float, float, float]
+color : tuple[float, ...]
     Normalized (R, G, B) vector with three components in the range 0..1.
 
 vertices : np.ndarray

docs/scan_format.rst

@@ -59,10 +59,10 @@ gender : :class:`~pyiconeus.models.Scan.GenderType`
     Gender of the subject
 
 transferDate : datetime.datetime
-    Date of the transfer
+    Date of the transfer, in seconds, time since 00:00:00 Coordinated Universal Time (UTC), Thursday, 1 January 1970, not counting leap seconds
 
 ageAtTransfer : int
-    Age at the transfer
+    Age at the transfer in days
 
 subjectDescription : str
     Description of the subject
@@ -77,10 +77,10 @@ Acquisition parameters
 ++++++++++++++++++++++++
 
 acquisitionMode : :class:`~pyiconeus.models.Scan.AcquisitionMode`
-    Description of the type of acquisition (ex: 3DScan, 4DScan, ...)
+    Description of the type of acquisition (ex: fUS3D, Angio3D, ...)
 
 acquisitionDate : datetime.datetime
-    Date of the acquisition
+    Date of the transfer, in seconds, time since 00:00:00 Coordinated Universal Time (UTC), Thursday, 1 January 1970, not counting leap seconds
 
 type : :class:`~pyiconeus.models.Scan.ScanType`
     'Source' or 'Proc', if the scan has been modified
@@ -101,19 +101,19 @@ ultrafastSamplingFrequency : float
     Frequency of the ultra fast sampling, in MHz
 
 planeWaveAngles : list[float]
-    List of the plane waves angles
+    List of the plane waves angles, in radians
 
 transmitVoltage : float
-    Voltage of the transmit
+    Voltage of the transmit, in volts
 
 delayAfterTrigger : float
-    Delay after each trigger
+    Delay after each trigger, in seconds
 
 isMultiplane : bool
     True if the acquisition is multiplane
 
 integrationWindowDuration : float
-    Time of the window duration
+    Time of the window duration, in seconds
 
 stimulationToggleTimes : list[float]
     List of the times the stimulation was toggled
@@ -123,8 +123,8 @@ Geometry, timing & data
 
 sizeX, sizeY, sizeZ : int
     Dimension of the acquisition:
-        - sizeX: Width size in number of voxels
-        - sizeY: Height size in number of voxels
+        - sizeX: Lateral size in number of voxels
+        - sizeY: Elevation size in number of voxels
         - sizeZ: Depth in number of voxels
 
 nTime : int
@@ -140,20 +140,20 @@ dim6 : :class:`~pyiconeus.models.Scan.Dim6`
     Description about additional filters, see the :ref:`dim6-section` section below.
 
 measuredTimes : list[float]
-    List containing the times of every acquired block
+    List containing the times of every acquired block, in seconds
 
 theoreticalTimeIndices : list[int]
     Indices of the measuredTimes list
 
 probeToLabsTranslations : numpy.ndarray
-    Array of mean translations, with shape ``(nPose, 3)``.
+    Array of translation in the Lab space, with shape ``(nPose, 3)``.
 
 probeToLabsRotations : numpy.ndarray
-    Array of rotations in radians, with shape ``(nPose, 3)``.
+    Array of euler angles in radians, with shape ``(nPose, 3)``.
 
-The :meth:`~pyiconeus.models.Scan.Scan.get_ProbeToLab` method combines these
+The :meth:`~pyiconeus.models.Scan.Scan.get_probe_to_lab` method combines these
 values into one 4x4 affine matrix per pose. The
-:meth:`~pyiconeus.models.Scan.Scan.get_VoxelToProbe` method returns the 4x4
+:meth:`~pyiconeus.models.Scan.Scan.get_voxel_to_probe` method returns the 4x4
 voxel-to-probe affine matrix.
 
 voxels : numpy.ndarray
@@ -180,7 +180,7 @@ dx, dy, dz : float
     Voxel size along each axis in meters
 
 dt : float
-    Time in seconds at the end of the acquisition of the first block of the first probe position including the pause. This is not necessarily volumetric dt
+    Time in seconds at the end of the first block of the first probe position including the pause. This is not necessarily volumetric dt
 
 dr : float
     Voxel angle in radians
@@ -209,7 +209,7 @@ probeElevationAperture : float or None
     Elevation aperture in millimeters when available.
 
 probeRadiusOfCurvature : float
-    in millimeters
+    Radius of curvature in millimeters.
 
 probeNumberOfElements : int or None
     Number of probe elements when available.
@@ -252,9 +252,15 @@ ClutterFiltering
 clutterFilter : clutterFilterType (``StaticSVD`` | ``DynamicSVD`` | ``Butterworth``)
 
 clutterFilterWindowDuration : float
-    Duration of the filter in seconds
+    Duration of the window in seconds
 
-clutterFilterCutoffLow, clutterFilterCutoffHigh : float
+clutterFilterCutoffLow, clutterFilterCutoffHigh:
+    For 'StaticSVD': int
+        - First and last singular value contribution
+    For 'DynamicSVD': int
+        - Low and high eigen values
+    For 'Butterworth': float
+        - Left edge of the first bin and right edge of the last bin
 
 VelocityBandwidthFiltering
 ++++++++++++++++++++++++++++
@@ -295,7 +301,7 @@ AcquisitionMode
 
 ``fUS2D``, ``Angio3D``, ``fUS3D``, ``fUS3DCustom``
 
-Legacy ``.scan`` files may store the raw acquisition-mode labels ``2DScan``,
-``3DScan``, ``4DScan``, ``4DScanCustom``, ``4DscanRCA`` and ``3DscanRCA``;
+Legacy ``.scan`` files may store the raw acquisition-mode labels ``2Dscan``,
+``3Dscan``, ``4Dscan``, ``4DscanCustom``, ``4DscanRCA`` and ``3DscanRCA``;
 the two RCA variants are remapped to ``fUS3D`` and ``Angio3D`` respectively
 when the file is read.

docs/usage.rst

@@ -58,7 +58,11 @@ Errors
 
 ``open_path`` raises ``FileNotFoundError`` when either path does not exist,
 ``ValueError`` for an unsupported extension, a missing/invalid ``.hraw``
-header, or an invalid block range, and ``OSError`` when a file cannot be read.
+header, or an invalid ``blockStart`` range. If ``blockEnd`` is
+greater than ``numberOfBlock``, it is clamped to the available number of
+blocks and a ``RuntimeWarning`` is emitted. ``blockEnd`` smaller than
+``blockStart`` raises ``RuntimeError``. Raises ``OSError`` when a file cannot be read,
+and ``TypeError`` if a non-integer argument is passed.
 
 More complete, runnable walkthroughs are available as notebooks in the
 `examples <https://github.com/Iconeus/PyIconeus/tree/main/examples>`_

src/pyiconeus/io/base.py

@@ -54,9 +54,9 @@ def open_path(
     Parameters
     ----------
 
-    **path**: str
+    **filepath**: str | os.PathLike[str]
         File path of the wanted PyIconeus object
-    **path2**: str (optional)
+    **raw_header_filepath**: str | os.PathLike[str] | None (optional)
         File path of the header file. (Only used with .raw files)
     **blockStart**: int = 1 (optional)
         The starting block number to get from the raw data

src/pyiconeus/models/Raw.py

@@ -27,7 +27,9 @@ class Raw:
     **metadata**: Raw.Metadata
         The metadata of the acquisition
     **data**: np.ndarray
-        The raw data of the acquisition
+        NumPy array containing the complex IQ data after beamforming. The leading
+        dimensions are ordered as ``(sizeZ, sizeY, sizeX, compound, frames, blocks)``
+        before singleton dimensions are removed by ``numpy.squeeze``.
     """
 
     class MetaData:
@@ -37,32 +39,35 @@ class MetaData:
         Attributes
         ----------
 
+        **acquisitionMode**: *str*
+            Description of the type of acquisition (ex: 2Dscan, 3Dscan, ...)
+
         **transmitFrequency**: float
-            The transmit frequency of the acquisition
+            The transmit frequency of the acquisition, in MHz
 
         **prf**: float
-            The pulse repetition frequency
+            The pulse repetition frequency, in Hz
 
         **speedOfSound**: float
-            The speed of sound
+            The speed of sound, in meter per second
 
         **frameRate**: float
-            Frame rate of the acquisition
+            Frame rate of the acquisition, in Hz
 
         **receiveAperture**: np.ndarray
-            Receive Aperture
+            Receive aperture, first and last elements of the aperture
 
         **depth**: Scan.Depth
-            Near and Far depth
+            Near and Far depth, in millimeter
 
         **flatAngles**: np.ndarray
-            Angles of the probe during the acquisition
+            Angles of the probe during the acquisition, in degrees
 
         **voxDim**: Scan.VoxDim
-            VoxDim data
+            Voxel dimension x, y, z, in millimeters
 
         **blockDim**: np.ndarray
-            BlockDim data
+            Block dimension x, y, z, angle, frame
 
         **compound**: bool
             True if the images are compounded, False otherwise
@@ -74,8 +79,6 @@ class MetaData:
             True if the file uses the legacy raw data block layout from
             early '.raw' acquisitions, False otherwise
 
-        **acquisitionMode**: *str*
-            Type of acquisition
         """
 
         @staticmethod

src/pyiconeus/models/Roi.py

@@ -23,17 +23,9 @@ class Roi:
     Attributes
     ----------
 
-    color: RoiColor
-        The displayed color of the Roi
+    list: list[RoiElements]
+        List containing the different ROIs of the file
 
-    label: str
-        The name of the Roi
-
-    vertices: np.ndarray (N, 3)
-        The points in Brain space of the volume
-
-    faces: np.ndarray (N, 3)
-        Each row contains the indices of the vertices composing a triangle of the volume
     """
 
     ROI_4CC_STR = "bri_"
@@ -102,6 +94,25 @@ def __str__(self) -> str:
 
 
 class RoiElements:
+    """
+    Region of Interest properties and values.
+
+    Attributes
+    ----------
+
+    color : tuple[float, ...]
+        Normalized (R, G, B) vector with three components in the range 0..1.
+
+    name: str
+        The name of the Roi
+
+    vertices: np.ndarray (N, 3)
+        The points in Brain space of the volume
+
+    faces: np.ndarray (N, 3)
+        Each row contains the indices of the vertices composing a triangle of the volume
+    """
+
     def __init__(
         self,
         color: tuple[float, ...],