some docstrings added / updated

src/iblphotometry/io.py

@@ -14,6 +14,16 @@
 def from_raw_neurophotometrics_file_to_raw_df(
     path: str | Path, validate=True, version='new'
 ) -> pd.DataFrame:
+    """ reads in a file as generated by the neurophotometrics FP3002 (both new and old versions) with validation
+
+    Args:
+        path (str | Path): path to the file, can be in either .csv or .pqt format
+        validate (bool, optional): If True, validates the file. Defaults to True.
+        version (str, optional): 'new' or 'old' version of the neurophotometrics file format. Defaults to 'new'.
+
+    Returns:
+        pd.DataFrame: the data as a raw dataframe format
+    """
     path = Path(path) if isinstance(path, str) else path
     match path.suffix:
         case '.csv':
@@ -30,6 +40,17 @@ def from_raw_neurophotometrics_file_to_raw_df(
 def from_raw_neurophotometrics_df_to_ibl_df(
     raw_df: pd.DataFrame, rois=None, drop_first=True
 ) -> pd.DataFrame:
+    """reads in a dataframe with the raw photometry data as generated by the neurophotometrics FP3002 into the ibl photometry dataformat.
+
+
+    Args:
+        raw_df (pd.DataFrame): as returned by `from_raw_neurophotometrics_file_to_raw_df`
+        rois (_type_, optional): names of the rois as selected by the user in the acquisition UI. If None, the names are inferred from the data. Defaults to None.
+        drop_first (bool, optional): Drop the The first frame, which has all LEDs on by default. Defaults to True.
+
+    Returns:
+        pd.DataFrame: the data in the ibl photometry data format
+    """
     if rois is None:
         rois = infer_data_columns(raw_df)
 
@@ -79,6 +100,17 @@ def from_raw_neurophotometrics_df_to_ibl_df(
 def from_raw_neurophotometrics_file_to_ibl_df(
     path: str | Path, drop_first=True, validate=True, version='new'
 ) -> pd.DataFrame:
+    """convenience function that chains `from_raw_neurophotometrics_file_to_raw_df` and `from_raw_neurophotometrics_df_to_ibl_df`. See docstrings
+
+    Args:
+        path (str | Path): _description_
+        drop_first (bool, optional): Drop the The first frame, which has all LEDs on by default. Defaults to True.
+        validate (bool, optional): If True, validates the file. Defaults to True.
+        version (str, optional): 'new' or 'old' version of the neurophotometrics file format. Defaults to 'new'.
+
+    Returns:
+        pd.DataFrame: _description_
+    """
     raw_df = from_raw_neurophotometrics_file_to_raw_df(
         path, validate=validate, version=version
     )
@@ -107,7 +139,7 @@ def from_ibl_dataframe(
 
     Args:
         ibl_df (pd.DataFrame): the dataframe, as stored in the photometry.signal.pqt
-        data_columns (list[str], optional): The names of the columns in the dataframe that contain the signals of different fibers. By default, they are named RegionXX. If None is provided, All columns that start with `Region` are treated as data columns. Defaults to None.
+        data_columns (list[str], optional): The names of the columns in the dataframe that contain the signals of different fibers. By default, they are named RegionXX. If None is provided, All columns that start with `Region` or `G` are treated as data columns. Defaults to None.
         time_column (str, optional): The name of the column that contains the timestamps. If None is provided, it is assumed that `time` is in the name. Defaults to None.
         channel_column (str, optional): The name of the column that contains. Defaults to 'name'.
         channel_names (list[str], optional): The names of the acquisition channel / frequency bands that are acquired. Defaults to None.
@@ -195,7 +227,17 @@ def from_ibl_dataframes(ibl_df: pd.DataFrame, locations_df: pd.DataFrame):
 def from_raw_neurophotometrics_file(
     path: str | Path, drop_first=True, validate=True, version='new'
 ) -> dict:
-    # this one bypasses everything
+    """reads in a file generated by the neurophotometrics FP3002 into the analysis ready format
+
+    Args:
+        path (str | Path): _description_
+        drop_first (bool, optional): Drop the The first frame, which has all LEDs on by default. Defaults to True.
+        validate (bool, optional): If True, validates the file. Defaults to True.
+        version (str, optional): 'new' or 'old' version of the neurophotometrics file format. Defaults to 'new'.
+
+    Returns:
+        dict: _description_
+    """
     ibl_df = from_raw_neurophotometrics_file_to_ibl_df(
         path, drop_first=drop_first, validate=validate, version=version
     )