Conversion API

Core API

File conversion CLI.

convert_h5_cmd(**kwargs)

Convert a raw mesoscale calcium recording session from HDF5 to an NWB file compatible with mesoscopy.

Source code in src/mesoscopy/convert/__init__.py

@convert_cmd.command("h5")
@click.argument(
    "input_path",
    type=click.Path(exists=True),
)
@click.option(
    "-o",
    "--out-dir",
    type=click.Path(),
    default="./",
    help="Output directory for converted file, defaults to current working directory. Will be created if it doesn't exist.",
)
@click.option(
    "-l",
    "--link-only",
    is_flag=True,
    show_default=True,
    default=False,
    help="Create a link to the HDF5 dataset instead of copying it over. If this is enabled, you MUST keep the raw HDF5 file - if you delete it, the data will also be gone.",
)
@click.option(
    "-f", "--frames-group", type=str, default="frames", help="HDF group path under which frame data is stored."
)
@click.option(
    "-t",
    "--timestamps-group",
    type=str,
    default="timestamps",
    help="HDF group path under which timestamp data is stored.",
)
@click.option(
    "-m",
    "--meta",
    "meta_path",
    type=click.Path(exists=True),
    help="Path to animal metadata file. Must be YAML or JSON format.",
)
@click.option("--subject-id", type=str, help="Metadata field - subject identifier.")
@click.option("--sex", type=click.Choice(["M", "F"], case_sensitive=False), help="Metadata field - subject sex.")
@click.option("--genotype", type=str, help="Metadata field - subject genotype.")
@click.option("--species", type=str, help="Metadata field - subject species.")
@click.option("--strain", type=str, help="Metadata field - subject strain.")
@click.option("--dob", type=str, help="Metadata field - subject date of birth in YYYY-MM-DD format (i.e. 1900-01-31).")
@click.option("--description", "session_description", type=str, help="Metadata field - session description.")
@click.option("--experimenter", type=str, help="Metadata field - experimenter name.")
@click.option("--lab", type=str, help="Metadata field - lab experiment was done in.")
@click.option("--institution", type=str, help="Metadata field - institution experiment was done in.")
def convert_h5_cmd(**kwargs: typing.Any) -> None:
    """Convert a raw mesoscale calcium recording session from HDF5 to an NWB file compatible with mesoscopy."""
    conv_h5.to_nwb(**kwargs)

convert_video_cmd(**kwargs)

Convert a raw mesoscale calcium recording session from video to an NWB file compatible with mesoscopy.

Source code in src/mesoscopy/convert/__init__.py

@convert_cmd.command("video")
@click.argument(
    "input_path",
    type=click.Path(exists=True),
)
@click.option(
    "-o",
    "--out-dir",
    type=click.Path(),
    default="./",
    help="Output directory for converted file, defaults to current working directory. Will be created if it doesn't exist.",
)
@click.option(
    "-t",
    "--ts-path",
    type=click.Path(exists=True),
    help="Path to timestamps file. Must be plain text or delimited.",
)
@click.option(
    "-d",
    "--ts-delimiter",
    type=click.Choice([",", "\t", " "], case_sensitive=False),
    default=",",
    help="Timestamp file delimiter, if file is delimited.",
)
@click.option(
    "-c",
    "--ts-column",
    type=int,
    help="Column in timestamp file to be used as timestamps. Must be provided if file is delimited and has more than one column.",
)
@click.option(
    "--ts-has-header",
    type=bool,
    is_flag=True,
    default=False,
    help="Flag signifying whether or not the timestamps file has a header row.",
)
@click.option(
    "-l",
    "--hdf5-only",
    is_flag=True,
    show_default=True,
    default=False,
    help="Generate an HDF5 linker file only without converting to NWB.",
)
@click.option(
    "-m",
    "--meta",
    "meta_path",
    type=click.Path(exists=True),
    help="Path to animal metadata file. Must be YAML or JSON format.",
)
@click.option("--subject-id", type=str, help="Metadata field - subject identifier.")
@click.option("--sex", type=click.Choice(["M", "F"], case_sensitive=False), help="Metadata field - subject sex.")
@click.option("--genotype", type=str, help="Metadata field - subject genotype.")
@click.option("--species", type=str, help="Metadata field - subject species.")
@click.option("--strain", type=str, help="Metadata field - subject strain.")
@click.option("--dob", type=str, help="Metadata field - subject date of birth in YYYY-MM-DD format (i.e. 1900-01-31).")
@click.option("--description", "session_description", type=str, help="Metadata field - session description.")
@click.option("--experimenter", type=str, help="Metadata field - experimenter name.")
@click.option("--lab", type=str, help="Metadata field - lab experiment was done in.")
@click.option("--institution", type=str, help="Metadata field - institution experiment was done in.")
def convert_video_cmd(**kwargs: typing.Any) -> None:
    """Convert a raw mesoscale calcium recording session from video to an NWB file compatible with mesoscopy."""
    if not kwargs.get("ts_path"):
        click.echo(
            "⚠️ WARNING - No timestamps file provided, using autogenerated timestamps. This might mess things up "
            "downstream."
        )
    if kwargs.pop("hdf5_only"):
        conv_vid.to_hdf5(**kwargs)
    else:
        conv_vid.to_nwb(**kwargs)

Metadata API

Animal metadata readers.

read_yaml(path)

Read a yaml metadata file.

Parameters:

• path (str) –

  Path to file.

Raises:

• ValueError –

  Raised if file contains fields not in DEFAULT_METADATA.

Returns:

• dict ( dict ) –

  Subject metadata.

Source code in src/mesoscopy/convert/metadata.py

def read_yaml(path: str) -> dict:
    """Read a yaml metadata file.

    Args:
        path (str): Path to file.

    Raises:
        ValueError: Raised if file contains fields not in DEFAULT_METADATA.

    Returns:
        dict: Subject metadata.
    """
    with open(path) as fp:
        metadata = yaml.safe_load(fp)

        for key in metadata.keys():
            if key not in list(DEFAULT_METADATA.keys()):
                raise ValueError(f"Invalid file contents - unrecognised key <{key}>.")

        for field in DEFAULT_METADATA:
            if field not in metadata.keys():
                metadata[field] = DEFAULT_METADATA.get(field)

        return metadata

read_json(path)

Read a json metadata file.

Parameters:

• path (str) –

  Path to file.

Raises:

• ValueError –

  Raised if file contains fields not in DEFAULT_METADATA.

Returns:

• dict ( dict ) –

  Subject metadata.

Source code in src/mesoscopy/convert/metadata.py

def read_json(path: str) -> dict:
    """Read a json metadata file.

    Args:
        path (str): Path to file.

    Raises:
        ValueError: Raised if file contains fields not in DEFAULT_METADATA.

    Returns:
        dict: Subject metadata.
    """
    with open(path) as fp:
        metadata = json.load(fp)

        for key in metadata.keys():
            if key not in list(DEFAULT_METADATA.keys()):
                raise ValueError(f"Invalid file contents - unrecognised key <{key}>.")

        for field in DEFAULT_METADATA:
            if field not in metadata.keys():
                metadata[field] = DEFAULT_METADATA.get(field)

        return metadata