Skip to content

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 
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
@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."""
    import mesoscopy.convert.hdf5 as conv_h5

    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 
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
@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."""
    import mesoscopy.convert.video as conv_vid

    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 
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
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 
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
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