Tutorials on Basics ==================== For those who are new to python and data analytics, we highly encourage you to go through `Prof. Josh Agar's tutorials `_ for a throrough primer on all the basic concepts. Here are a list of other tutorials from other websites and sources that describe some of the many important topics on reading, using / running and writing code: .. contents:: :local: Python and packages -------------------- There are several concepts such as file operations, parallel computing, etc. that are heavily used and applied in pyUSID. Most of these concepts are realized using add-ons or packages in python. Here is a compilation of useful tutorials: Python ~~~~~~ The following tutorials go over the basics of python programming: * `Official Python tutorial `_ * The `Hitchhiker guide to Python `_ * Introduction to programming in `Python 3 `_ * Tutorials on a broad spectrum of `real-world use topics `_ HDF5 and h5py ~~~~~~~~~~~~~ Our software packages - ``sidpy``, ``pyUSID``, ``pyNSID`` are all designed to be file-centric, we highly recommend learning more about HDF5 and h5py: * `Basics of HDF5 `_ (especially the last three tutorials) * `Quick start `_ to h5py * Another `tutorial on HDF5 and h5py `_ Installing software ------------------- python ~~~~~~~ `Anaconda `_ is a popular source for python which also comes with a large number of popular scientific python packages that are all correctly compiled and installed in one go. Tutorial for `installing Anaconda `_ (Python + all necessary packages) python packages ~~~~~~~~~~~~~~~~ Two popular methods for installing packages in python are: * `pip `_: * included with basic python and standard on Linux and Mac OS * Works great for installing pure python and other simple packages * `conda `_ * included with Anaconda installation * Ideally suited for installing packages that have complex dependencies * Here's a nice tutorial on `installing packages using both pip and conda `_ Updating packages ~~~~~~~~~~~~~~~~~ Following `these instructions `_, open a terminal or the command prompt (Windows) and type: .. code:: bash conda update conda conda update anaconda Note that you could use the following line instead of or in addition to ``conda update anaconda`` but it can lead to incompatible package versions .. code:: bash conda update --all Note that this does **not** update python itself. Upgrading python ~~~~~~~~~~~~~~~~ Follow these instructions to `upgrade python using conda `_ to the latest or specific version Writing code ------------ Text Editors ~~~~~~~~~~~~ These software often do not have any advanced features found in IDEs such as syntax highlighting, real-time code-checking etc. but are simple, and most importantly, open files quickly. Here are some excellent text editors for each class of operating system: * Mac OS - `Atom `_ * Linux - `gEdit `_, `vim `_, `neovim `_ * Windows - `Notepad++ `_ Integrated Development Environments (IDE) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ These applications often come with a built-in text editor, code management capabilities, a python console, a terminal, integration with software repositories, etc. that make them ideal for executing and developing code. We only recommend two IDEs at this point: Spyder for users, PyCharm for developers. Both of these work in Linux, Mac OS, and Windows. * `Spyder `_ is a great IDE that is simple and will be immediately familiar for users of Matlab. * `Basics of Spyder `_ * `Python with Spyder `_ - this was written with Python 2.7 in mind, but most concepts will still apply * `Pycharm `_ * Official `PyCharm Tutorial `_ from Jetbrains * `VS Code `_ * Completely free and open-source editor by Microsoft. Much faster and extremely lightweight compared to Pycharm. Jupyter Notebooks ~~~~~~~~~~~~~~~~~ These are `interactive documents `_ containing live cells with code, equations, visualizations, and narrative text. The interactive nature of the document makes Jupyter notebooks an ideal medium for conveying information and a narrative. These documents are neither text editors nor IDEs and are a separate category. * Notebook `basics `_ * `Video `_ tutorial * Another `video overview `_. Software development basics --------------------------- This section is mainly focused on the other tools that are mainly necessary for those interested in developing their own code and possibly contributing back to sidpy. Environments ~~~~~~~~~~~~ Environments allow users to set up and segregate software sandboxes. For example, one could set up separate environments in python 2 and 3 to ensure that a certain desired code works in both python 2 and 3. For python users, there are two main and popular modes of creating and managing environments - **virtual environments** and **conda environments**. * `Virtual environment `_ * Basic python ships with virtual enviroments. Anaconda is not required for this * How to `use venv `_ * Conda environments * `Basics `_ of Conda * How to `manage environments in conda `_ * `Managing Python Environments `_ with Conda Version control ~~~~~~~~~~~~~~~ `Version control `_ is a tool used for managing changes in code over time. It lifts the burden of having to check for changes line-by-line when multiple people are working on the same project. For example, sidpy uses `Git `_, the most popular version control software (VCS) for tracking changes etc. By default, git typically only comes with a command-line interface. However, there are several software packages that provide a graphical user interface on top of git. One other major benefit of using an IDE over jupyter or a text editor is that (some) IDEs come with excellent integration with VCS like Git. Here are a collection of useful resources to get you started on git: * Tutorial on the `basics of git `_ * Our favorite git client - `GitKraken `_ * Our favorite IDE with `excellent integration with Git: PyCharm `_ * Our own guide to `setting up and using git with PyCharm `_