add algo docs

[ReiHashimoto]

• [No.22] パラメータの説明機能の実装 oist/optinist#537

概要

パラメータ説明機能の実装に向け、アルゴリズムをリファクタリング

• アルゴリズムはAlgoTemplateクラスを継承して実装する
• パラメータはpydanticのBaseModelを継承して実装する

APIスキーマは一部変更されているが、各種yamlファイルの構成には影響がないため、下位互換性を持つ

ドキュメンテーションにアルゴリズムのドキュメントを自動生成

• autodoc-pydanticを使用
• サイドメニューからの導線も追加
• 以下のコマンドで確認可能

  make docs
  

関数の実装方法詳細

# 以下のmoduleをimport
from pydantic import BaseModel
from pydantic.dataclasses import Field

from studio.app.common.core.algo import AlgoTemplate


# 関数のパラメータはpydanticのBaseModelを継承し、Fieldで実装する
class ParamX(BaseModel):
    param_xa: int = Field(  # use Field with type definition
        1, # default value
        description="param_a's doc."
    )
    param_xb: str = Field(
        "paramB",
        alias="123param"  # Pythonの文法上使用できないパラメータ名(数字で始まる)、pydanticで使われているパラメータ名("copy"など)の場合はaliasを使用する
        description="param_b's doc."
    )


class ParamY(BaseModel):
    param_ya: bool = Field(False)


# 以下のような形式でパラメータをネストさせることができる
class SomeFunctionParam(BaseModel):
    param_x: ParamX = Field(ParamX())
    param_y: ParamY = Field(ParamY())


# AlgoTemplateを継承して実装する
class SomeFunction(AlgoTemplate):
    def run(  # runの関数名でoverrideする
        self,
        params: SomeFunctionParams,  # パラメータのクラスを型として渡す
        images: ImageData, # input nodeとなるデータクラス
    ) -> dict(  # output nodeとなるデータクラス
        fluorescence=FluoData,
        iscell=IscellData
    ):
        # function_id, output_dirはselfから取得できる
        print(self.output_dir)
        print(self.function_id)
        
        # nwbパラメータも同様にselfから取得できる
        # 元々引数として明示はなかったが、一部関数ではimaging_rateを取得するためにkwargsから取り出していた
        fr = self.nwb_params.get("imaging_plane", {}).get("imaging_rate", 30)
        
        # 処理を別メソッドに切り出す場合、classmethodまたはstaticmethodとして定義して呼び出す
        related_results = self.related_function(x, y)
        
        ...
        return info

@classmethod
def related_function(cls, param_x, param_y):
    ...
    return z

ToDo

• edit_ROIの関数を新方式での実装に対応させる

[itutu-tienday]

ノード関数ファイルの編集方法（以下での説明内容）のテキストは、docs の配下への格納でしょうか。

• add algo docs #232 (comment)

[ReiHashimoto]

こちらToDo漏れていましたね、そちらのドキュメントを更新します。

[itutu-tienday]

caiman cnmfe の実行時、以下のエラーが発生。
※develop-main でも発生しているようなので、当件とは別件そうですが、念のため一旦内容を記載。

Traceback (most recent call last): File "/home/iam/workspaces/projects/araya/010_optinist/barebone-studio/studio/app/common/core/rules/runner.py",
line 43, in run output_info = cls.execute_function( File
"/home/iam/workspaces/projects/araya/010_optinist/barebone-studio/studio/app/common/core/rules/runner.py",
line 128, in execute_function algo() File
"/home/iam/workspaces/projects/araya/010_optinist/barebone-studio/studio/app/optinist/wrappers/caiman/cnmfe.py",
line 129, in run CaimanCnmf() File
"/home/iam/workspaces/projects/araya/010_optinist/barebone-studio/studio/app/optinist/wrappers/caiman/cnmf.py",
line 187, in run ims = np.stack(ims) File "<__array_function__ internals>",
line 180, in stack File
"/home/iam/workspaces/projects/araya/010_optinist/barebone-studio/.snakemake/conda/555e5a3f793f921de7713969efaf5f8c_/lib/python3.8/site-packages/numpy/core/shape_base.py",
line 422, in stack raise ValueError('need at least one array to stack')
ValueError: need at least one array to stack