Skip to content

Commit 29de8e6

Browse files
FynnBeFynnBe
committed
update 'Get started' section
1 parent b9897da commit 29de8e6

File tree

1 file changed

+234
-91
lines changed

1 file changed

+234
-91
lines changed

‎README.md

Lines changed: 234 additions & 91 deletions
Original file line numberDiff line numberDiff line change
@@ -13,97 +13,252 @@ Python specific core utilities for bioimage.io resources (in particular models).
1313

1414
To get started we recommend installing bioimageio.core with conda together with a deep
1515
learning framework, e.g. pytorch, and run a few `bioimageio` commands to see what
16-
bioimage.core offers.
16+
bioimage.core has to offer:
1717

1818
1. install with conda (for more details on conda environments, [checkout the conda docs](https://conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html))
1919

20-
```console
21-
install -c conda-forge bioimageio.core pytorch
22-
```
20+
```console
21+
conda install -c conda-forge bioimageio.core pytorch
22+
```
2323

2424
1. test a model
2525

26-
```console
27-
bioimageio test powerful-chipmunk
26+
```console
27+
$ bioimageio test powerful-chipmunk
28+
...
29+
```
2830

29-
testing powerful-chipmunk...
31+
<details>
32+
<summary>(Click to expand output)</summary>
3033

31-
✔️ bioimageio validation passed
32-
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
33-
source https://uk1s3.embassy.ebi.ac.uk/public-datasets/bioimage.io/powerful-chipmunk/1/files/rdf.yaml
34-
format version model 0.4.10
35-
bioimageio.spec 0.5.3post4
36-
bioimageio.core 0.6.8
34+
```console
3735

3836

37+
✔️ bioimageio validation passed
38+
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
39+
source https://uk1s3.embassy.ebi.ac.uk/public-datasets/bioimage.io/powerful-chipmunk/1/files/rdf.yaml
40+
format version model 0.4.10
41+
bioimageio.spec 0.5.3post4
42+
bioimageio.core 0.6.8
3943

40-
❓ location detail
41-
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
42-
✔️ initialized ModelDescr to describe model 0.4.10
4344

44-
✔️ bioimageio.spec format validation model 0.4.10
45-
🔍 context.perform_io_checks True
46-
🔍 context.root https://uk1s3.embassy.ebi.ac.uk/public-datasets/bioimage.io/powerful-chipmunk/1/files
47-
🔍 context.known_files.weights.pt 3bd9c518c8473f1e35abb7624f82f3aa92f1015e66fb1f6a9d08444e1f2f5698
48-
🔍 context.known_files.weights-torchscript.pt 4e568fd81c0ffa06ce13061327c3f673e1bac808891135badd3b0fcdacee086b
49-
🔍 context.warning_level error
5045

51-
✔️ Reproduce test outputs from test inputs
46+
❓ location detail
47+
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
48+
✔️ initialized ModelDescr to describe model 0.4.10
5249

53-
✔️ Reproduce test outputs from test inputs
54-
```
50+
✔️ bioimageio.spec format validation model 0.4.10
51+
🔍 context.perform_io_checks True
52+
🔍 context.root https://uk1s3.embassy.ebi.ac.uk/public-datasets/bioimage.io/powerful-chipmunk/1/files
53+
🔍 context.known_files.weights.pt 3bd9c518c8473f1e35abb7624f82f3aa92f1015e66fb1f6a9d08444e1f2f5698
54+
🔍 context.known_files.weights-torchscript.pt 4e568fd81c0ffa06ce13061327c3f673e1bac808891135badd3b0fcdacee086b
55+
🔍 context.warning_level error
5556

56-
1. run prediction on your data
57+
✔️ Reproduce test outputs from test inputs
5758

58-
- display the `bioimageio-predict` command interface
59+
✔️ Reproduce test outputs from test inputs
60+
```
5961

60-
```console
61-
> bioimageio predict -h
62-
usage: bioimageio predict [-h] [--inputs {str,Sequence[str]}] [--outputs {str,Sequence[str]}] [--overwrite bool]
63-
[--blockwise bool] [--stats Path]
64-
SOURCE
65-
66-
bioimageio-predict - Run inference on your data with a bioimage.io model.
67-
68-
positional arguments:
69-
SOURCE Url/path to a bioimageio.yaml/rdf.yaml file or a bioimage.io resource identifier, e.g.
70-
'affable-shark'
71-
72-
optional arguments:
73-
-h, --help show this help message and exit
74-
--inputs {str,Sequence[str]}
75-
model inputs Either a single path/glob pattern including `{tensor_id}` to be used for all
76-
model inputs, or a list of paths/glob patterns for each model input respectively. For models
77-
with a single input a single path/glob pattern with `{tensor_id}` is also accepted.
78-
(default: model_inputs/*/{tensor_id}.*)
79-
--outputs {str,Sequence[str]}
80-
output paths analog to `inputs` (default: outputs_{model_id}/{sample_id}/{tensor_id}.npy)
81-
--overwrite bool allow overwriting existing output files (default: False)
82-
--blockwise bool process inputs blockwise (default: False)
83-
--stats Path path to dataset statistics (will be written if it does not exist, but the model requires
84-
statistical dataset measures) (default: model_inputs\dataset_statistics.json)
85-
```
62+
</details>
8663

87-
- locate your input data
88-
- predict away!
64+
or
8965

90-
```console
91-
bioimageio predict affable-shark
92-
```
66+
```console
67+
$ bioimageio test impartial-shrimp
68+
...
69+
```
70+
71+
<details><summary>(Click to expand output)</summary>
72+
73+
```console
74+
✔️ bioimageio validation passed
75+
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
76+
source https://uk1s3.embassy.ebi.ac.uk/public-datasets/bioimage.io/impartial-shrimp/1.1/files/rdf.yaml
77+
format version model 0.5.3
78+
bioimageio.spec 0.5.3.2
79+
bioimageio.core 0.6.9
80+
81+
82+
❓ location detail
83+
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
84+
✔️ initialized ModelDescr to describe model 0.5.3
85+
86+
87+
✔️ bioimageio.spec format validation model 0.5.3
88+
89+
🔍 context.perform_io_checks False
90+
🔍 context.warning_level error
91+
92+
✔️ Reproduce test outputs from test inputs (pytorch_state_dict)
93+
94+
95+
✔️ Run pytorch_state_dict inference for inputs with batch_size: 1 and size parameter n:
96+
97+
0
98+
99+
✔️ Run pytorch_state_dict inference for inputs with batch_size: 2 and size parameter n:
100+
101+
0
102+
103+
✔️ Run pytorch_state_dict inference for inputs with batch_size: 1 and size parameter n:
104+
105+
1
106+
107+
✔️ Run pytorch_state_dict inference for inputs with batch_size: 2 and size parameter n:
108+
109+
1
110+
111+
✔️ Run pytorch_state_dict inference for inputs with batch_size: 1 and size parameter n:
112+
113+
2
114+
115+
✔️ Run pytorch_state_dict inference for inputs with batch_size: 2 and size parameter n:
116+
117+
2
93118

94-
- for convenience the command line arguments may be given in a `bioimageio-cli.json` or `bioimageio-cli.yaml` file.
95-
The YAML file takes priority over the JSON file.
96-
Addtional command line arguments take the highest priority.
97-
98-
```yaml
99-
# bioimageio-cli.yaml
100-
inputs: inputs/*_{tensor_id}.h5
101-
outputs: outputs_{model_id}/{sample_id}_{tensor_id}.h5
102-
overwrite: true
103-
blockwise: true
104-
stats: inputs/dataset_statistics.json
119+
✔️ Reproduce test outputs from test inputs (torchscript)
120+
121+
122+
✔️ Run torchscript inference for inputs with batch_size: 1 and size parameter n: 0
123+
124+
125+
✔️ Run torchscript inference for inputs with batch_size: 2 and size parameter n: 0
126+
127+
128+
✔️ Run torchscript inference for inputs with batch_size: 1 and size parameter n: 1
129+
130+
131+
✔️ Run torchscript inference for inputs with batch_size: 2 and size parameter n: 1
132+
133+
134+
✔️ Run torchscript inference for inputs with batch_size: 1 and size parameter n: 2
135+
136+
137+
✔️ Run torchscript inference for inputs with batch_size: 2 and size parameter n: 2
138+
```
139+
140+
</details>
141+
1. run prediction on your data
142+
143+
- display the `bioimageio-predict` command help to get an overview:
144+
145+
```console
146+
$ bioimageio predict --help
147+
...
148+
```
149+
150+
<details>
151+
<summary>(Click to expand output)</summary>
152+
153+
```console
154+
usage: bioimageio predict [-h] [--inputs Sequence[Union[str,Annotated[Tuple[str,...],MinLenmin_length=1]]]]
155+
[--outputs {str,Tuple[str,...]}] [--overwrite bool] [--blockwise bool] [--stats Path]
156+
[--preview bool]
157+
[--weight_format {typing.Literal['keras_hdf5','onnx','pytorch_state_dict','tensorflow_js','tensorflow_saved_model_bundle','torchscript'],any}]
158+
[--example bool]
159+
SOURCE
160+
161+
bioimageio-predict - Run inference on your data with a bioimage.io model.
162+
163+
positional arguments:
164+
SOURCE Url/path to a bioimageio.yaml/rdf.yaml file
165+
or a bioimage.io resource identifier, e.g. 'affable-shark'
166+
167+
optional arguments:
168+
-h, --help show this help message and exit
169+
--inputs Sequence[Union[str,Annotated[Tuple[str,...],MinLen(min_length=1)]]]
170+
Model input sample paths (for each input tensor)
171+
172+
The input paths are expected to have shape...
173+
- (n_samples,) or (n_samples,1) for models expecting a single input tensor
174+
- (n_samples,) containing the substring '{input_id}', or
175+
- (n_samples, n_model_inputs) to provide each input tensor path explicitly.
176+
177+
All substrings that are replaced by metadata from the model description:
178+
- '{model_id}'
179+
- '{input_id}'
180+
181+
Example inputs to process sample 'a' and 'b'
182+
for a model expecting a 'raw' and a 'mask' input tensor:
183+
--inputs="[["a_raw.tif","a_mask.tif"],["b_raw.tif","b_mask.tif"]]"
184+
(Note that JSON double quotes need to be escaped.)
185+
186+
Alternatively a `bioimageio-cli.yaml` (or `bioimageio-cli.json`) file
187+
may provide the arguments, e.g.:
188+
```yaml
189+
inputs:
190+
- [a_raw.tif, a_mask.tif]
191+
- [b_raw.tif, b_mask.tif]
192+
```
193+
194+
`.npy` and any file extension supported by imageio are supported.
195+
Aavailable formats are listed at
196+
https://imageio.readthedocs.io/en/stable/formats/index.html#all-formats.
197+
Some formats have additional dependencies.
198+
199+
  (default: ('{input_id}/001.tif',))
200+
--outputs {str,Tuple[str,...]}
201+
Model output path pattern (per output tensor)
202+
203+
All substrings that are replaced:
204+
- '{model_id}' (from model description)
205+
- '{output_id}' (from model description)
206+
- '{sample_id}' (extracted from input paths)
207+
208+
  (default: outputs_{model_id}/{output_id}/{sample_id}.tif)
209+
--overwrite bool allow overwriting existing output files (default: False)
210+
--blockwise bool process inputs blockwise (default: False)
211+
--stats Path path to dataset statistics
212+
(will be written if it does not exist,
213+
but the model requires statistical dataset measures)
214+
  (default: dataset_statistics.json)
215+
--preview bool preview which files would be processed
216+
and what outputs would be generated. (default: False)
217+
--weight_format {typing.Literal['keras_hdf5','onnx','pytorch_state_dict','tensorflow_js','tensorflow_saved_model_bundle','torchscript'],any}
218+
The weight format to use. (default: any)
219+
--example bool generate and run an example
220+
221+
1. downloads example model inputs
222+
2. creates a `{model_id}_example` folder
223+
3. writes input arguments to `{model_id}_example/bioimageio-cli.yaml`
224+
4. executes a preview dry-run
225+
5. executes prediction with example input
226+
227+
  (default: False)
228+
```
229+
230+
</details>
231+
232+
- create an example and run prediction locally!
233+
234+
```console
235+
$ bioimageio predict impartial-shrimp --example=True
236+
...
237+
```
238+
239+
<details>
240+
<summary>(Click to expand output)</summary>
241+
242+
```console
243+
🛈 bioimageio prediction preview structure:
244+
{'{sample_id}': {'inputs': {'{input_id}': '<input path>'},
245+
'outputs': {'{output_id}': '<output path>'}}}
246+
🔎 bioimageio prediction preview output:
247+
{'1': {'inputs': {'input0': 'impartial-shrimp_example/input0/001.tif'},
248+
'outputs': {'output0': 'impartial-shrimp_example/outputs/output0/1.tif'}}}
249+
predict with impartial-shrimp: 100%|███████████████████████████████████████████████████| 1/1 [00:21<00:00, 21.76s/sample]
250+
🎉 Sucessfully ran example prediction!
251+
To predict the example input using the CLI example config file impartial-shrimp_example\bioimageio-cli.yaml, execute `bioimageio predict` from impartial-shrimp_example:
252+
$ cd impartial-shrimp_example
253+
$ bioimageio predict "impartial-shrimp"
254+
255+
Alternatively run the following command in the current workind directory, not the example folder:
256+
$ bioimageio predict --preview=False --overwrite=True --stats="impartial-shrimp_example/dataset_statistics.json" --inputs="[[\"impartial-shrimp_example/input0/001.tif\"]]" --outputs="impartial-shrimp_example/outputs/{output_id}/{sample_id}.tif" "impartial-shrimp"
257+
(note that a local 'bioimageio-cli.json' or 'bioimageio-cli.yaml' may interfere with this)
105258
```
106259

260+
</details>
261+
107262
## Installation
108263

109264
### Via Mamba/Conda
@@ -180,32 +335,20 @@ You can list all the available commands via:
180335
bioimageio
181336
```
182337

183-
Check that a model adheres to the model spec:
184-
185-
```console
186-
bioimageio validate <MODEL>
187-
```
188-
189-
Test a model (including prediction for the test input):
190-
191-
```console
192-
bioimageio test-model <MODEL>
193-
```
194-
195-
Run prediction for an image stored on disc:
338+
### CLI inputs from file
196339

197-
```console
198-
bioimageio predict-image <MODEL> --inputs <INPUT> --outputs <OUTPUT>
199-
```
340+
For convenience the command line options (not arguments) may be given in a `bioimageio-cli.json`
341+
or `bioimageio-cli.yaml` file, e.g.:
200342

201-
Run prediction for multiple images stored on disc:
202-
203-
```console
204-
bioimagei predict-images -m <MODEL> -i <INPUT_PATTERN> - o <OUTPUT_FOLDER>
343+
```yaml
344+
# bioimageio-cli.yaml
345+
inputs: inputs/*_{tensor_id}.h5
346+
outputs: outputs_{model_id}/{sample_id}_{tensor_id}.h5
347+
overwrite: true
348+
blockwise: true
349+
stats: inputs/dataset_statistics.json
205350
```
206351
207-
`<INPUT_PATTERN>` is a `glob` pattern to select the desired images, e.g. `/path/to/my/images/*.tif`.
208-
209352
## 🐍 Use in Python
210353
211354
`bioimageio.core` is a python package that implements prediction with bioimageio models

0 commit comments

Comments
 (0)