{"id":21480616,"url":"https://github.com/flatironinstitute/normcorre","last_synced_at":"2025-12-25T06:13:20.996Z","repository":{"id":16296443,"uuid":"75439599","full_name":"flatironinstitute/NoRMCorre","owner":"flatironinstitute","description":"Matlab routines for online non-rigid motion correction of calcium imaging data","archived":false,"fork":false,"pushed_at":"2022-05-29T15:19:21.000Z","size":78329,"stargazers_count":150,"open_issues_count":5,"forks_count":95,"subscribers_count":31,"default_branch":"master","last_synced_at":"2025-04-11T09:52:57.057Z","etag":null,"topics":["algorithm","calcium-imaging","matlab","motion-correction","registration","subpixel-registration"],"latest_commit_sha":null,"homepage":"","language":"MATLAB","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/flatironinstitute.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"license.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-12-02T23:39:26.000Z","updated_at":"2025-04-01T02:49:13.000Z","dependencies_parsed_at":"2022-09-20T07:03:15.912Z","dependency_job_id":null,"html_url":"https://github.com/flatironinstitute/NoRMCorre","commit_stats":null,"previous_names":["simonsfoundation/normcorre"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/flatironinstitute/NoRMCorre","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flatironinstitute%2FNoRMCorre","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flatironinstitute%2FNoRMCorre/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flatironinstitute%2FNoRMCorre/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flatironinstitute%2FNoRMCorre/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/flatironinstitute","download_url":"https://codeload.github.com/flatironinstitute/NoRMCorre/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flatironinstitute%2FNoRMCorre/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":271424969,"owners_count":24757374,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-21T02:00:08.990Z","response_time":74,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["algorithm","calcium-imaging","matlab","motion-correction","registration","subpixel-registration"],"created_at":"2024-11-23T12:16:55.244Z","updated_at":"2025-11-01T09:04:19.301Z","avatar_url":"https://github.com/flatironinstitute.png","language":"MATLAB","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Join the chat at https://gitter.im/epnev/ca_source_extraction](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/epnev/ca_source_extraction?utm_source=badge\u0026utm_medium=badge\u0026utm_campaign=pr-badge\u0026utm_content=badge)\n\n# NoRMCorre: Non-Rigid Motion Correction \nThis package provides a Matlab implementation of the NoRMCorre algorithm [[1]](#ref), and can be used for online piecewise rigid motion correction of 2d (planar) or 3d (volumetric) calcium imaging data. \n\n## Citation\n\nIf you find this package useful please cite the companion paper [[1]](#ref):\n\n```\n@article{pnevmatikakis2017normcorre,\n  title={NoRMCorre: An online algorithm for piecewise rigid motion correction of calcium imaging data},\n  author={Pnevmatikakis, Eftychios A and Giovannucci, Andrea},\n  journal={Journal of neuroscience methods},\n  volume={291},\n  pages={83--94},\n  year={2017},\n  publisher={Elsevier}\n}\n```\n\n## Synopsis\n\nThe algorithm operates by splitting the field of view into a set of overlapping patches. For each patch and each frame a rigid translation is estimated by aligning the patch against a template using an efficient, FFT based, algorithm for subpixel registration [[2]](#reg). The estimated set of translations is further upsampled to a finer resolution to create a smooth motion field that is applied to a set of smaller overlapping patches. Extra care is taken to avoid smearing caused by interpolating overlapping patches with drastically different motion vectors. The registered frame is used to update the template in an online fashion by calculating a running/mean of past registered frames. The pipeline is summarized in the figure below.\n\n![Alt text](pipeline.png?raw=true \"piecewise rigid motion correction pipeline\")\n\n## Code details\n\nSee the function [```demo.m```](https://github.com/simonsfoundation/NoRMCorre/blob/master/demo.m) for an example of the code. The algorithm is implemented in the function ```normcorre.m```. If you have access to the parallel computing toolbox, then the function ```normcorre_batch.m``` can offer speed gains by enabling within mini-batch parallel processing. The user gives a dataset (either as 3D or 4D tensor loaded in RAM or memory mapped, or a pointer to a .tiff stack or .hdf5 file), and a parameters struct ```options```. Optionally, an initial template can also be given. The algorithm can also be used for motion correction of 1p micro-endoscopic data, by estimating the shifts on high pass spatially filtered version of the data. See the script [```demo_1p.m```](https://github.com/simonsfoundation/NoRMCorre/blob/master/demo_1p.m) for an example.\n\nThe algorithm can also be ran using the MotionCorrection object. See [```demo_mc_class.m```](https://github.com/simonsfoundation/NoRMCorre/blob/master/demo_mc_class.m) for an example on how to use the object for 2p and 1p data.\n\nThe ```options``` struct can be set either manually or by using the function ```NoRMCorreSetParms.m```. Some parameters of the ```options``` struct are the following:\n\n| Parameter name | Description |\n|----------------|-------------|\n| ```d1,d2,d3``` | dimensions of field of view |\n| ```grid_size``` | size of non-overlapping portion of each patch the grid in each direction (x-y-z)|\n| ```overlap_pre```| size of overlapping region in each direction before upsampling  |\n| ```mot_uf```    | upsampling factor for smoothing and refinement of motion field |\n| ```overlap_post ``` | size of overlapping region in each direction after upsampling |\n| ```max_shift``` | maximum allowed shift for rigid translation | \n| ```max_dev``` | maximum deviation of each patch from estimated rigid translation |\n| ```upd_template``` | update the template online after registering some frames |\n| ```bin_width``` | length of bin over which the registered frames are averaged to update the template |\n| ```init_batch``` | number of frames to be taken for computing initial template |\n| ```iter``` | number of times to go over the dataset |\n| ```output_type``` | type of output registered file |\n| ```phase_flag``` | flag for using phase correlation |\n| ```correct_bidir``` | check for offset due to bidirectional scanning (default: true) |\n\nThe performance of registration can be evaluated using the function ```motion_metrics.m```. The function simply computes the correlation coefficient of each (registered) frame, with the mean (registered) frame across time, the mean registered frame, and its crispness.\n\n## Developers\n\n[Eftychios A. Pnevmatikakis](https://github.com/epnev), Flatiron Institure, Simons Foundation\n\n## External packages\n\nThis package includes functions from the following packages\n- [Save and load a multipage tiff file](https://www.mathworks.com/matlabcentral/fileexchange/35684-save-and-load-a-multiframe-tiff-image/content/loadtiff.m)\n- [Savefast](https://www.mathworks.com/matlabcentral/fileexchange/39721-save-mat-files-more-quickly) for saving (and then loading) MAT files more quickly without compressing their contents. \n- [Eficient subpixel registration by cross-correlation](https://www.mathworks.com/matlabcentral/fileexchange/18401-efficient-subpixel-image-registration-by-cross-correlation) for fast alignment of an image against a template.\n\n## Integrations \n\nThis package will be integrated with the [Matlab code](https://www.github.com/epnev/ca_source_extraction) for source extraction and deconvolution using CNMF.\n\nA python version of this algorithm developed from [Andrea A. Giovannuci](https://github.com/agiovann) is included as part of the [CaImAn](https://github.com/simonsfoundation/CaImAn) package that provides a complete pipeline for calcium imaging data pre-processing.\n\nAlthough the two implementations give almost identical results for the same input file, there are some slight differences in the way they are called and their capabilities. These differences are highlighted [here.](https://github.com/simonsfoundation/NoRMCorre/wiki/Differences-between-Matlab-and-Python-implementations)\n\n## More details, contact information, and citing NoRMCorre\n\nCheck the [wiki](https://github.com/simonsfoundation/NoRMCorre/wiki) for more details and some frequently asked questions. \n\nPlease use the [gitter chat room](https://gitter.im/epnev/ca_source_extraction?utm_source=badge\u0026utm_medium=badge\u0026utm_campaign=pr-badge\u0026utm_content=badge) for questions and comments, and create an issue for any bugs you might encounter.\n\nIf you find this package useful please cite the following paper:\n\nEftychios A. Pnevmatikakis and Andrea Giovannucci, *NoRMCorre: An online algorithm for piecewise rigid motion correction of calcium imaging data*, Journal of Neuroscience Methods, vol. 291, pp 83-94, 2017; doi: [https://doi.org/10.1016/j.jneumeth.2017.07.031](https://doi.org/10.1016/j.jneumeth.2017.07.031)\n\n## Acknowledgements\n\nThe 2p example dataset is kindly provided from Andrea Giovannucci, taken at Wang lab (Princeton University).\nThe 1p example dataset is kindly provided by Daniel Aharoni and Peyman Golshani (UCLA, [Miniscope project](http://miniscope.org)).\n\n## References \n\n\u003ca name=\"ref\"\u003e\u003c/a\u003e[1] Eftychios A. Pnevmatikakis and Andrea Giovannucci, *NoRMCorre: An online algorithm for piecewise rigid motion correction of calcium imaging data*, Journal of Neuroscience Methods, vol. 291, pp 83-94, 2017; doi: [https://doi.org/10.1016/j.jneumeth.2017.07.031](https://doi.org/10.1016/j.jneumeth.2017.07.031)\n\n\u003ca name=\"reg\"\u003e\u003c/a\u003e[2] Guizar-Sicairos, M., Thurman, S. T., \u0026 Fienup, J. R. (2008). Efficient subpixel image registration algorithms. Optics letters, 33(2), 156-158. Matlab implementation available [here](https://www.mathworks.com/matlabcentral/fileexchange/18401-efficient-subpixel-image-registration-by-cross-correlation).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflatironinstitute%2Fnormcorre","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fflatironinstitute%2Fnormcorre","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflatironinstitute%2Fnormcorre/lists"}