Hello! This guide will help you to get started with ArchaeoPY. This will cover installations you will need, how to utilise our repository, and how to get going running code. Stay tuned for Python Basics and Coding Basics guides! We are just in the process of putting them into a more GitHub/external-user-friendly form from our ipython notebook server.
1. Getting Started: Anaconda:
First things first, you will need Python installed on your computer. We recommend running Python 2.7 through Anaconda: http://continuum.io/downloads
Anaconda is a great cross-platform environment to work in. It includes Spyder, our preferred IDE for it support of scientific applications. For a further brief overview of Anaconda, check out their quick start guide: https://store.continuum.io/static/img/Anaconda-Quickstart.pdf
2. Getting Started: GitHub Repository
ArchaeoPY code is hosted on GitHub: https://github.com/archaeopy
To participate in collaborative work and download a local copy of the repository to your computer, create an account with GitHub. For managing a local copy of the repository on your computer, we recommend downloading and using GitHub for Windows (https://windows.github.com/), which we have found to be very straightforward and user-friendly. Using a mac? (https://mac.github.com/)
Once you have these installed on your computer, navigate to the ArchaeoPY GitHub repository and click on "Fork." Forking the repository will save a copy of the repository to your account. When you sync and refresh the repository, you will receive the most recent updates. You can make changes to the code, but it won't affect the "master code" unless you send a request for your changes to be approved and update the code.
To save a local copy to your computer, press "Clone on Desktop." GitHub for Windows/Mac should open and ask you where you would like the local repository to be saved to. Once cloned, you should now see the update histories to the code! To ensure you are using the latest version, press "Sync."
If you run into any issues for these steps, please post a comment or send a message to the Google Groups, and we can send you a step-by-step guide with images.
3. Getting Familiar
After downloading and installing Anaconda, open Spyder. If you load Spyder, you should see something like this:
On the left-hand side, you can type in code and save as a Python script (.py). On the right-hand side is the Spyder console, which you can use as an interpreter.
An example on running the ArchaeoPY modeller software:
1. In Spyder: File > Load, and navigate to where your local repository has been copied. In the folder ArchaeoPY-Modeller, open the file main.py
2. To run the software, press F6 or Run > Configure. We recommend to always run in your code in a "New Dedicated Python Interpreter," or "Execute in an external system terminal" (**Side note: I have found that the ArchaeoPY Modeller GUI will not show when I run main.py in a new dedicated interpreter, but will show when I run rough through an external system terminal.):
The ArchaeoPY Modeller GUI should appear:
Layout and Documenting Your Work
As one of ArchaeoPY's objectives is to develop a dynamic, open-source repository for our code, it is imperative that we layout and document our work properly! This ensures that other people can easily understand, run, and change our codes. Have a look through the PEP 8 style guide and please try to adhere to them, as we should strive for consistency. I have highlighted a few salient guidelines from PEP 8 below:
- Line Length: Limit your lines to 79 characters. Notice how in Spyder there is a faint vertical line running down your editor? This line delimits the 79 character limit. Instead of writing out the entire command in one line, we can break it up by using \, and continuing on the next line.
- Documentation: As ArchaeoPy members, we will strive to properly document our codes; so they can be easily understood, used, and modified by other users. To document your code, write comments after the # symbol, which are ignored when the code is run. Three apostrophes at the start and end of ignored text also works: ''' Ignored text '''
- Naming Variables: Strive to give your variables descriptive names. Since we are following the PEP 8 guidelines, for variable names we will use underscores to separate the words (e.g. my_name vs. myName).
Have a look through ArchaeoPY.org for some of our tutorials. Basic Python and NumPy tutorials will be published soon; as we are just in the process of converting our ipython notebooks to something that we can better utilise on here and in our GitHub. In the mean time, below more links to some of our favourite online tutorials!
The basics, how to think like a computer scientist: http://openbookproject.net/thinkcs/python/english2e/
The basics, the "hard" way: http://learnpythonthehardway.org/book/
Project Euler, use python to solve logic and mathematical questions: https://projecteuler.net/
Stay tuned for more!