Merge pull request #147 from nel-lab/better-docstrings

made better docstrings

mesmerize_core/batch_utils.py

@@ -24,7 +24,7 @@ def set_parent_raw_data_path(path: Union[Path, str]) -> Path:
 
  Parameters
  ----------
- path: Union[Path, str]
+ path: Path or str
  Full parent data path
  """
  global PARENT_DATA_PATH
@@ -41,10 +41,11 @@ def set_parent_raw_data_path(path: Union[Path, str]) -> Path:
 def get_parent_raw_data_path() -> Path:
  """
  Get the global `PARENT_DATA_PATH`
+
  Returns
  -------
  Path
- global `PARENT_DATA_PATH`
+ global `PARENT_DATA_PATH` as a Path object
 
  """
  global PARENT_DATA_PATH
@@ -59,6 +60,14 @@ def set_batch_path(self, path: Union[str, Path]):
  self._data.attrs["batch_path"] = Path(path)
 
  def get_batch_path(self) -> Path:
+ """
+ Get the full path to the batch dataframe file
+
+ Returns
+ -------
+ Path
+ full path to the batch dataframe file as a Path object
+ """
  if "batch_path" in self._data.attrs.keys():
  if self._data.attrs["batch_path"] is not None:
  return self._data.attrs["batch_path"]
@@ -67,17 +76,18 @@ def get_batch_path(self) -> Path:
 
  def resolve(self, path: Union[str, Path]) -> Path:
  """
- Resolve the full path of ``path`` if possible, first tries batch_dir then raw_data_dir
- Last resort plain resolve.
+ Resolve the full path of the passed ``path`` if possible, first tries
+ "batch_dir" then "raw_data_dir".
 
  Parameters
  ----------
- path: Union[str, Path]
+ path: str or Path
  The relative path to resolve
 
  Returns
  -------
- Full path with the batch path or raw data path appended
+ Path
+ Full path with the batch path or raw data path appended
 
  """
  path = Path(path)
@@ -95,15 +105,16 @@ def resolve(self, path: Union[str, Path]) -> Path:
  def split(self, path: Union[str, Path]):
  """
  Split a full path into (batch_dir, relative_path) or (raw_data_dir, relative_path)
+
  Parameters
  ----------
- path: Union[str, Path]
+ path: str or Path
  Full path to split with respect to batch_dir or raw_data_dir
 
  Returns
  -------
  Tuple[Path, Path]
- (<batch_dir or raw_data_dir>, <relative_path>)
+ (<batch_dir> or <raw_data_dir>, <relative_path>)
 
  """
  path = Path(path)
@@ -139,11 +150,11 @@ class PathsSeriesExtension(_BasePathExtensions):
 
 def load_batch(path: Union[str, Path]) -> pd.DataFrame:
  """
- Load the batch pickle file, also sets the global `CURRENT_BATCH_PATH`
+ Load the batch dataframe pickle file
 
  Parameters
  ----------
- path: Union[str, Path])
+ path: str or Path
 
  Returns
  -------
@@ -163,13 +174,11 @@ def load_batch(path: Union[str, Path]) -> pd.DataFrame:
  df.head()
 
  """
- # global CURRENT_BATCH_PATH
+
  path = validate_path(path)
 
  df = pd.read_pickle(Path(path))
 
- # CURRENT_BATCH_PATH = pathlib.Path(batch_file)
-
  df.paths.set_batch_path(path)
 
  return df
@@ -181,11 +190,11 @@ def create_batch(path: Union[str, Path], remove_existing: bool = False) -> pd.Da
 
  Parameters
  ----------
- path: Union[str. Path]
- path to save the new batch DataFrame
+ path: str or Path
+ path to save the new batch DataFrame as a pickle file
 
  remove_existing: bool
- If `True`, remove an existing batch DataFrame file if it exists at the given `path`
+ If ``True``, remove an existing batch DataFrame file if it exists at the given `path`, default ``False``
 
  Returns
  -------
@@ -220,9 +229,6 @@ def create_batch(path: Union[str, Path], remove_existing: bool = False) -> pd.Da
 
  df.to_pickle(path)
 
- # global CURRENT_BATCH_PATH
- # CURRENT_BATCH_PATH = path
-
  return df
 
 

mesmerize_core/caiman_extensions/cnmf.py

@@ -88,7 +88,8 @@ def __init__(self, s: pd.Series):
  @validate("cnmf")
  def get_cnmf_memmap(self, mode: str = "r") -> np.ndarray:
  """
- Get the CNMF C-order memmap
+ Get the CNMF C-order memmap. This should NOT be used for viewing the
+ movie frames use ``caiman.get_input_movie()`` for that purpose.
 
  Parameters
  ----------
@@ -189,13 +190,12 @@ def get_masks(
 
  Parameters
  ----------
- component_indices: optional, Union[np.ndarray, str]
+ component_indices: str or np.ndarray, optional
  | indices of the components to include
- | if ``np.ndarray``, uses these indices in the provided array
- | if ``"good"`` uses good components, i.e. cnmf.estimates.idx_components
- | if ``"bad"`` uses bad components, i.e. cnmf.estimates.idx_components_bad
  | if not provided, ``None``, or ``"all"`` uses all components
-
+ | if ``"good"`` uses good components, i.e. ``Estimates.idx_components``
+ | if ``"bad"`` uses bad components, i.e. ``Estimates.idx_components_bad``
+ | if ``np.ndarray``, uses the indices in the provided array
 
  threshold: float
  threshold
@@ -264,12 +264,12 @@ def get_contours(
 
  Parameters
  ----------
- component_indices: optional, Union[np.ndarray, str]
+ component_indices: str or np.ndarray, optional
  | indices of the components to include
- | if ``np.ndarray``, uses these indices in the provided array
- | if ``"good"`` uses good components, i.e. cnmf.estimates.idx_components
- | if ``"bad"`` uses bad components, i.e. cnmf.estimates.idx_components_bad
  | if not provided, ``None``, or ``"all"`` uses all components
+ | if ``"good"`` uses good components, i.e. ``Estimates.idx_components``
+ | if ``"bad"`` uses bad components, i.e. ``Estimates.idx_components_bad``
+ | if ``np.ndarray``, uses the indices in the provided array
 
  swap_dim: bool
  swap the x and y coordinates, use if the contours don't align with the cells in your image
@@ -366,12 +366,12 @@ def get_temporal(
 
  Parameters
  ----------
- component_indices: optional, Union[np.ndarray, str]
+ component_indices: str or np.ndarray, optional
  | indices of the components to include
- | if ``np.ndarray``, uses these indices in the provided array
- | if ``"good"`` uses good components, i.e. cnmf.estimates.idx_components
- | if ``"bad"`` uses bad components, i.e. cnmf.estimates.idx_components_bad
  | if not provided, ``None``, or ``"all"`` uses all components
+ | if ``"good"`` uses good components, i.e. ``Estimates.idx_components``
+ | if ``"bad"`` uses bad components, i.e. ``Estimates.idx_components_bad``
+ | if ``np.ndarray``, uses the indices in the provided array
 
  add_background: bool
  if ``True``, add the temporal background, ``cnmf.estimates.C + cnmf.estimates.f``
@@ -660,7 +660,7 @@ def run_detrend_dfof(
  ) -> None:
  """
  | Uses caiman's detrend_df_f.
- | call ``cnmf.get_detrend_dfof()`` to get the values.
+ | call ``CNMF.get_detrend_dfof()`` to get the values.
  | Sets ``CNMF.estimates.F_dff``
 
  Warnings
@@ -728,12 +728,12 @@ def get_detrend_dfof(
 
  Parameters
  ----------
- component_indices: optional, Union[np.ndarray, str]
+ component_indices: str or np.ndarray, optional
  | indices of the components to include
- | if ``np.ndarray``, uses these indices in the provided array
- | if ``"good"`` uses good components, i.e. cnmf.estimates.idx_components
- | if ``"bad"`` uses bad components, i.e. cnmf.estimates.idx_components_bad
  | if not provided, ``None``, or ``"all"`` uses all components
+ | if ``"good"`` uses good components, i.e. ``Estimates.idx_components``
+ | if ``"bad"`` uses bad components, i.e. ``Estimates.idx_components_bad``
+ | if ``np.ndarray``, uses the indices in the provided array
 
  return_copy: bool
  | if ``True`` returns a copy of the cached value in memory.
@@ -818,7 +818,7 @@ def run_eval(self, params: dict) -> None:
  @validate("cnmf")
  def get_good_components(self) -> np.ndarray:
  """
- get the good component indices, ``CNMF.estimates.idx_components``
+ get the good component indices, ``Estimates.idx_components``
 
  Returns
  -------
@@ -833,7 +833,7 @@ def get_good_components(self) -> np.ndarray:
  @validate("cnmf")
  def get_bad_components(self) -> np.ndarray:
  """
- get the bad component indices, ``CNMF.estimates.idx_components_bad``
+ get the bad component indices, ``Estimates.idx_components_bad``
 
  Returns
  -------

mesmerize_core/caiman_extensions/common.py

@@ -164,8 +164,9 @@ def remove_item(self, index: Union[int, str, UUID], remove_data: bool = True, sa
 
  Parameters
  ----------
- index: Union[int, str, UUID]
- The index of the batch item to remove from the DataFrame
+ index: int, str or UUID
+ The index of the batch item to remove from the DataFrame as a numerical ``int`` index, ``str`` representing
+ a UUID, or a UUID object.
 
  remove_data: bool
  if ``True`` removes all output data associated to the batch item from disk.
@@ -270,14 +271,14 @@ def get_children(self, index: Union[int, str, UUID]) -> List[UUID]:
 
  Parameters
  ----------
- index: Union[int, str, UUID]
- the index of the mcorr item to get the children of
+ index: int, str, or UUID
+ the index of the mcorr item to get the children of, provided as a numerical ``int`` index, str representing
+ a UUID, or a UUID object
 
  Returns
  -------
  List[UUID]
  List of UUIDs of child CNMF items
-
  """
 
  if not self._df.iloc[index]["algo"] == "mcorr":
@@ -311,12 +312,13 @@ def get_parent(self, index: Union[int, str, UUID]) -> Union[UUID, None]:
 
  Parameters
  ----------
- index: Union[int, str, UUID]
- the index of the batch item to get the parent of
+ index: int, str, or UUID
+ the index of the batch item to get the parent of, provided as a numerical ``int`` index, str representing
+ a UUID, or a UUID object
 
  Returns
  -------
- Union[UUID, None]
+ UUID or None
  | if ``UUID``, this is the UUID of the batch item whose output was used for the input of the batch item at
  the provided ``index``
 
@@ -408,8 +410,9 @@ def run(
 
  Parameters
  ----------
- backend: Optional[str]
- One of the available backends, if none default is `COMPUTE_BACKEND_SUBPROCESS`
+ backend: str, optional
+ One of the available backends, default on Linux & Mac is ``"subprocess"``. Default on Windows is
+ ``"local"`` since Windows is inconsistent in the way it launches subprocesses
 
  **kwargs
  any kwargs to pass to the backend
@@ -492,7 +495,7 @@ def get_input_movie(self, reader: callable = None) -> Union[np.ndarray, Any]:
  Parameters
  ----------
  reader: callable
- a function that return an array-like
+ a function that take the input movie path and return an array-like
 
  Returns
  -------