README.rst 8.86 KB
Newer Older
Somnath, Suhas's avatar
Somnath, Suhas committed
1
==========
2
pycroscopy		|statusimage|
Somnath, Suhas's avatar
Somnath, Suhas committed
3
4
==========

5
6
.. |statusimage| image:: https://travis-ci.org/pycroscopy/pycroscopy.svg?branch=master

Somnath, Suhas's avatar
Somnath, Suhas committed
7
8
9
10
.. contents::

What is pycroscopy?
-------------------
Somnath, Suhas's avatar
Somnath, Suhas committed
11
pycroscopy is a `python <http://www.python.org/>`_ package for image processing and scientific analysis of imaging modalities such as multi-frequency scanning probe microscopy, scanning tunneling spectroscopy, x-ray diffraction microscopy, and transmission electron microscopy. pycroscopy uses a data-centric model wherein the raw data collected from the microscope, results from analysis and processing routines are all written to standardized hierarchical data format (HDF5) files for traceability, reproducibility, and provenance.
12
13

With  `pycroscopy <https://pycroscopy.github.io/pycroscopy/>`_ we aim to:
Somnath, Suhas's avatar
Somnath, Suhas committed
14
15
16
17
	1. Serve as a hub for collaboration across scientific domains (microscopists, material scientists, biologists...)
	2. provide a community-developed, open standard for data formatting 
	3. provide a framework for developing data analysis routines 
	4. significantly lower the barrier to advanced data analysis procedures by simplifying I/O, processing, visualization, etc.
Somnath, Suhas's avatar
Somnath, Suhas committed
18

Somnath, Suhas's avatar
Somnath, Suhas committed
19
To learn more about the motivation, general structure, and philosophy of pycroscopy, please read this `short introduction <https://github.com/pycroscopy/pycroscopy/blob/master/docs/pycroscopy_2017_07_11.pdf>`_.
20

Somnath, Suhas's avatar
Somnath, Suhas committed
21
22
Package Structure
-----------------
Somnath, Suhas's avatar
Somnath, Suhas committed
23
The package structure is simple, with 4 main modules:
Somnath, Suhas's avatar
Somnath, Suhas committed
24
25
26
27
   1. **io**: Reading and writing to HDF5 files + translating data from custom & proprietary microscope formats to HDF5.
   2. **processing**: multivariate statistics, machine Learning, and signal filtering.
   3. **analysis**: model-dependent analysis of information.
   4. **viz**: Plotting functions and interactive jupyter widgets to visualize multidimenional data
nlaanait's avatar
nlaanait committed
28

Somnath, Suhas's avatar
Somnath, Suhas committed
29
Once a user converts their microscope's data format into an HDF5 format, using some of the `Translator` classes in `io`, the user gains access to the rest of the utilities present in `pycroscopy.*`. 
Somnath, Suhas's avatar
Somnath, Suhas committed
30

Somnath, Suhas's avatar
Somnath, Suhas committed
31
32
Installation
------------
33

Somnath, Suhas's avatar
Somnath, Suhas committed
34
Pycroscopy requires many commonly used python packages such as numpy, scipy etc. To simplify the installation process, we recommend the installation of Anaconda which contains most of the prerequisite packages as well as a development environment - Spyder. 
Somnath, Suhas's avatar
Somnath, Suhas committed
35

Somnath, Suhas's avatar
Somnath, Suhas committed
36
0. Recommended - uninstall existing Python distribution(s) if installed.  Restart computer afterwards.
37

Somnath, Suhas's avatar
Somnath, Suhas committed
38
1. Install Anaconda 4.2 (Python 3.5) 64-bit -  `Mac <https://repo.continuum.io/archive/Anaconda3-4.2.0-MacOSX-x86_64.pkg>`_ / `Windows <https://repo.continuum.io/archive/Anaconda3-4.2.0-Windows-x86_64.exe>`_ / `Linux <https://repo.continuum.io/archive/Anaconda3-4.2.0-Linux-x86_64.sh>`_
Somnath, Suhas's avatar
Somnath, Suhas committed
39

Somnath, Suhas's avatar
Somnath, Suhas committed
40
2. Install pycroscopy - Open a terminal (mac / linux) or command prompt (windows - if possible with administrator priveleges) and type:
Somnath, Suhas's avatar
Somnath, Suhas committed
41

Somnath, Suhas's avatar
Somnath, Suhas committed
42
.. code:: bash
Somnath, Suhas's avatar
Somnath, Suhas committed
43

Somnath, Suhas's avatar
Somnath, Suhas committed
44
	   pip install pycroscopy
Somnath, Suhas's avatar
Somnath, Suhas committed
45

Somnath, Suhas's avatar
Somnath, Suhas committed
46
3. Enjoy pycroscopy!
Somnath, Suhas's avatar
Somnath, Suhas committed
47

Somnath, Suhas's avatar
Somnath, Suhas committed
48
If you already have pycroscopy installed and want to update to the latest version, use the following command:
Somnath, Suhas's avatar
Somnath, Suhas committed
49

Somnath, Suhas's avatar
Somnath, Suhas committed
50
.. code:: bash
Somnath, Suhas's avatar
Somnath, Suhas committed
51

Somnath, Suhas's avatar
Somnath, Suhas committed
52
  pip install -U --no-deps pycroscopy
Somnath, Suhas's avatar
Somnath, Suhas committed
53
54
55
56
57
58
59
  
If it does not work try reinstalling the package:

.. code:: bash

  pip uninstall pycroscopy
  pip install pycroscopy
Somnath, Suhas's avatar
Somnath, Suhas committed
60

Somnath, Suhas's avatar
Somnath, Suhas committed
61
62
If you would like to quickly view HDF5 files generated by and used in pycroscopy, we recommend `HDF View <https://support.hdfgroup.org/products/java/hdfview/>`_

Somnath, Suhas's avatar
Somnath, Suhas committed
63
64
65
66
67
Compatibility
~~~~~~~~~~~~~
* Pycroscopy was initially developed in python 2 but all current / future development for pycroscopy will be on python 3.5+. Nonetheless, we will do our best to ensure continued compatibility with python 2. 
* We currently do not support 32 bit architectures

68
69
Getting Started
---------------
Somnath, Suhas's avatar
Somnath, Suhas committed
70
* Follow the instructions above to install pycroscopy
Somnath, Suhas's avatar
Somnath, Suhas committed
71
* See how we use pycroscopy for our scientific research in these `jupyter notebooks <http://nbviewer.jupyter.org/github/pycroscopy/pycroscopy/tree/master/jupyter_notebooks/>`_. Many of them are linked to journal publications listed below.
Somnath, Suhas's avatar
Somnath, Suhas committed
72
	* Please see the official `jupyter <http://jupyter.org>`_ website for more information about notebooks and consider watching this `youtube video <https://www.youtube.com/watch?v=HW29067qVWk>`_.
73
* See our `examples <https://pycroscopy.github.io/pycroscopy/auto_examples/index.html>`_ to get started on using and writing your own pycroscopy functions
Somnath, Suhas's avatar
Somnath, Suhas committed
74
* Videos and other tutorials are available at the `Institute For Functional Imaging of Materials <http://ifim.ornl.gov/resources.html>`_ 
75
* For more information about our functions and classes, please see our `API <https://pycroscopy.github.io/pycroscopy/pycroscopy.html>`_
Somnath, Suhas's avatar
Somnath, Suhas committed
76
77
* We have many translators that transform data from popular microscope data formats to pycroscopy compatible .h5 files. We also have `tutorials to get you started on importing your data to pycroscopy <https://pycroscopy.github.io/pycroscopy/auto_examples/tutorial_01_translator.html>`_. 
* Details regarding the defention, implementation, and guidelines for pycroscopy's `data format <https://pycroscopy.github.io/pycroscopy/Data_Format.html>`_ for `HDF5 <https://github.com/pycroscopy/pycroscopy/blob/master/docs/Pycroscopy_Data_Formatting.pdf>`_ are also available. 
Somnath, Suhas's avatar
Somnath, Suhas committed
78
* If you are interested in contributing and are looking for topics we are / will work on, please look at our `To Do <https://github.com/pycroscopy/pycroscopy/blob/master/ToDo.rst>`_ page
Somnath, Suhas's avatar
Somnath, Suhas committed
79

Somnath, Suhas's avatar
Somnath, Suhas committed
80
81
Journal Papers using pycroscopy
-------------------------------
82
1. `Big Data Analytics for Scanning Transmission Electron Microscopy Ptychography <https://www.nature.com/articles/srep26348>`_ by S. Jesse et al., Scientific Reports (2015); jupyter notebook `here 1 <http://nbviewer.jupyter.org/github/pycroscopy/pycroscopy/blob/master/jupyter_notebooks/Ptychography.ipynb>`_
Somnath, Suhas's avatar
Somnath, Suhas committed
83
 
84
2. `Rapid mapping of polarization switching through complete information acquisition <http://www.nature.com/articles/ncomms13290>`_ by S. Somnath et al., Nature Communications (2016); jupyter notebook `here 2 <http://nbviewer.jupyter.org/github/pycroscopy/pycroscopy/blob/master/jupyter_notebooks/G_mode_filtering.ipynb>`_
Somnath, Suhas's avatar
Somnath, Suhas committed
85
 
86
3. `Improving superconductivity in BaFe2As2-based crystals by cobalt clustering and electronic uniformity <http://www.nature.com/articles/s41598-017-00984-1>`_ by L. Li et al., Scientific Reports (2017); jupyter notebook `here 3 <http://nbviewer.jupyter.org/github/pycroscopy/pycroscopy/blob/master/jupyter_notebooks/STS_LDOS.ipynb>`_
Somnath, Suhas's avatar
Somnath, Suhas committed
87
 
88
4. `Direct Imaging of the Relaxation of Individual Ferroelectric Interfaces in a Tensile-Strained Film <http://onlinelibrary.wiley.com/doi/10.1002/aelm.201600508/full>`_ by L. Li et al.; Advanced Electronic Materials (2017), jupyter notebook `here 4 <http://nbviewer.jupyter.org/github/pycroscopy/pycroscopy/blob/master/jupyter_notebooks/BE_Processing.ipynb>`_
Somnath, Suhas's avatar
Somnath, Suhas committed
89

Somnath, Suhas's avatar
Somnath, Suhas committed
90
5. `Decoding apparent ferroelectricity in perovskite nanofibers <http://pubs.acs.org/doi/pdf/10.1021/acsami.7b14257>`_ by R. Ganeshkumar et al., ACS Applied Materials & Interfaces (2017). 
Somnath, Suhas's avatar
Somnath, Suhas committed
91

Somnath, Suhas's avatar
Somnath, Suhas committed
92
6. Ultrafast Current Imaging via Bayesian Inference by S. Somnath et al., accepted at Nature Communications (2017).
Somnath, Suhas's avatar
Somnath, Suhas committed
93
94
95
96

7. Feature extraction via similarity search: application to atom finding and denosing in electon and scanning probe microscopy imaging by S. Somnath et al.; under review at Advanced Structural and Chemical Imaging (2017), jupyter notebook `here 5 <http://nbviewer.jupyter.org/github/pycroscopy/pycroscopy/blob/master/jupyter_notebooks/Image_Cleaning_Atom_Finding.ipynb>`_

8. Many more coming soon....
97

Somnath, Suhas's avatar
Somnath, Suhas committed
98
99
International conferences and workshops using pycroscopy
--------------------------------------------------------
Somnath, Suhas's avatar
Somnath, Suhas committed
100
* Dec 2017 - Materials Research Society conference
101
102
103
* Oct 31 2017 @ 6:30 PM - American Vacuum Society conference;  Session: SP-TuP1; poster 1641
* Aug 9 2017 @ 8:30 - 10:00 AM - Microscopy and Microanalysis conference; X40 - Tutorial session on `Large Scale Data Acquisition and Analysis for Materials Imaging and Spectroscopy <http://microscopy.org/MandM/2017/program/tutorials.cfm>`_ by S. Jesse and S. V. Kalinin
* Aug 8 2017 @ 10:45 AM - Microscopy and Microanalysis conference - poster session
Somnath, Suhas's avatar
Somnath, Suhas committed
104
105
* Apr 2017 - Lecture on `atom finding <https://physics.appstate.edu/events/aberration-corrected-stem-teaching-machines-and-atomic-forge>`_
* Dec 2016 - Poster + `abstract <https://mrsspring.zerista.com/poster/member/85350>`_ at the 2017 Spring Materials Research Society (MRS) conference
Somnath, Suhas's avatar
Somnath, Suhas committed
106

Somnath, Suhas's avatar
Somnath, Suhas committed
107
108
Contact us
----------
109
* We are interested in collaborating with industry members to integrate pycroscopy into instrumentation or analysis software and can help in exporting data to pycroscopy compatible .h5 files 
110
* We can work with you to convert your file formats into pycroscopy compatible HDF5 files and help you get started with data analysis.
Somnath, Suhas's avatar
Somnath, Suhas committed
111
* Join our slack project at https://pycroscopy.slack.com to discuss about pycroscopy
Somnath, Suhas's avatar
Somnath, Suhas committed
112
* Feel free to get in touch with us at pycroscopy (at) gmail [dot] com
Somnath, Suhas's avatar
Somnath, Suhas committed
113
* If you find any bugs or if you want a feature added to pycroscopy, raise an `issue <https://github.com/pycroscopy/pycroscopy/issues>`_. You will need a free Github account to do this