registration speed-up parameters (e.g nb iterations)

[Borda]

Is your feature request related to a problem? Please describe. We are registering large microscopy images using this package which works fine meaning the alignment is reasonably good but it takes a very long time... I found that there are some parameters like reg_iterations or syn_sampling but I feel confused what it does or how to use it...

• reg_iterations is number of iterations per image pyramid or transformation type?
• syn_sampling is sampling in the spatial domain (image pixel grid) or trasformation

Describe the solution you'd like Having s short recommendation what parameters should be tuned and approximate direction (lower -> faster, ...) of possible changes

Describe alternatives you've considered Having a parameter for the

• maximal number of iteration
• tolerance values of the resulting transformation
• registration step / sampling

Additional context We are using ANTsPy for registering images from ANHIR dataset of average image size 12k x 10k and the resulting alignment is quite fine, but it takes horribly long, about 2hours per image pair.

[ntustison]

I'll first answer your specific questions and then provide additional details to give you a better sense of how the antsRegistration capabilities differ between ANTsPy/ANTsR and the original C++ implementation:

reg_iterations is number of iterations per image pyramid or transformation type?

number of iterations for the final registration

syn_sampling is sampling in the spatial domain (image pixel grid) or trasformation

spatial domain

The registration tools in both ANTsPy and ANTsR are simplifications of the original antsRegistration tool in our ANTs package. Specifically, the latter is a generic registration tool which allows one to concatenate stages in a serial fashion to construct any combination of transformation models for best determining correspondence between image pairs. For example, in brain registration, one will typically do rigid ---> affine ---> deformable. However, with the C++ antsRegistration tool one can also do something completely unorthodox like deformable --> similarity --> deformable --> rigid --> affine --> deformable. This normally wouldn't make much sense for the general image correspondence problem but one could do it. In ANTsPy and ANTsR, we have wrapped this generic tool into certain use cases to make it easier on the user. One can see this in the source code and by simply looking at all the different transformation types. Because most of our applications (and those of the ANTs user base) are neuroimaging, these wrapper cases are targeted to brain imaging with much different image sizes such that they might not be well-suited for your histological applications. For example, I wouldn't be surprised if you're wasting a lot of computational time in the linear alignment stages and I would assume you're definitely using higher-than-necessary resolutions during the SyN stage and that is probably consuming most of your time.

Looking at the source code, it doesn't look like the generic tool is accessible through the ANTsPy interface. In that case, you might want to have a go at developing your own histological alignment protocol using the core C++ antsRegistration tool and then, perhaps pushing that back into ANTsPy/ANTsR as it's own transformation wrapper.

[Borda]

@ntustison thank you for your quick reply and clarification of the ANTsPy package. One more parameter grad_step is also spatial, right? and what are the units? I think that it would be helpful to add to the documentation info about parameter units if they are pixels/voxels or some relative values and for relative values some range...

Could you please help me (give some recommendations) what parameters shall I use to large microscopy images (average 10kx10k pixels)... what about:

 initial_transform='AffineFast',
 type_of_transform='ElasticSyN',
 grad_step=5,
 aff_metric='mattes',
 aff_sampling=32,
 syn_metric='mattes',
 syn_sampling=32,
 reg_iterations=(30, 20, 10),

Btw, what are the kwargs, are they listed somewhere?

[ntustison]

grad_step is also spatial, right? and what are the units?

Yes, in voxel units and it's suggested that they stay < 0.5 to meet theoretical numerical stability considerations.

I think that it would be helpful to add to the documentation info about parameter units if they are pixels/voxels or some relative values and for relative values some range...

You're right. If you could make a pull request with some suggested edits, then that would be really helpful for us. Documentation is, unfortunately, something that too often gets neglected due to time constraints.

I see that you posted over on the ANTsX/ANTs forum regarding this issue so I'll write more over there. As I mentioned previously, since these "canned" parameter sets are not targeted for image registration problem, I would avoid using ANTsPy for now. Instead, you should develop your own parameter set for this particular application in ANTs and then we can discuss migration to ANTsPy, if that's ultimately the route you want to go. More over at ANTsX/ANTs.

[stnava]

**kwargs lets you pass command line arguments directly to antsRegistration. see how it is used here https://github.com/ANTsX/ANTsPy/blob/8c182cf7d499e3413c67280d017c8a38f873b518/ants/registration/interface.py#L1199-L1201

[seralouk]

**kwargs lets you pass command line arguments directly to antsRegistration. see how it is used here

https://github.com/ANTsX/ANTsPy/blob/8c182cf7d499e3413c67280d017c8a38f873b518/ants/registration/interface.py#L1199-L1201

I was wondering if I could make ants.registration run in parallel (multiple cores) instead of only one. Is that possible?

[ntustison]

That's determined by the environmental variable assignment, e.g., ITK_GLOBAL_DEFAULT_NUMBER_OF_THREADS=4. Does that not work for you?

[seralouk]

I am using the python version of ANTsPy on a linux server.

Would an export ITK_GLOBAL_DEFAULT_NUMBER_OF_THREADS=50 be sufficient? If yes, I still do not see many cores used while running ants.registration.

[stnava]

It should work although I don’t remember ever explicitly checking ... Is important that this is set before you import ants.

On Tue, Oct 1, 2019 at 11:00 AM Serafeim Loukas notifications@github.com wrote:

I am using the python version of ANTsPy on a linux server.

Would an export ITK_GLOBAL_DEFAULT_NUMBER_OF_THREADS=50 be sufficient? If yes, I still do not see many cores used while running ants.registration .

— You are receiving this because you commented.

Reply to this email directly, view it on GitHub https://github.com/ANTsX/ANTsPy/issues/85?email_source=notifications&email_token=AACPE7THJMKMF4SLKXABVKDQMNQ2NA5CNFSM4IYHR6HKYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOEABSS2A#issuecomment-537078120, or mute the thread https://github.com/notifications/unsubscribe-auth/AACPE7XPUBXYETX2XHUJF73QMNQ2NANCNFSM4IYHR6HA .

--

brian

[seralouk]

I see. One last thing. To set the environmental variable before importing ants:

import os
os.environ["ITK_GLOBAL_DEFAULT_NUMBER_OF_THREADS"] = "50"
import ants

is this the right way or should I do this through bash?

If yes, I still cannot see many cores working when using ants.registration

[Borda]

I believe that it is not clear, thx. see also https://github.com/ANTsX/ANTs/issues/850