Guidelines For Contributors

Write the first paragraph of your page here.

You Can Help Us
Since almost every experiment could benefit from a data analysis package, we aim to produce one for each experiment, however this is extremely time consuming, which is why we need help from able programmers. Ideally, you will have had experience with MATLAB (or other programming language) beyond the PhysXXXX "Introduction to Programming" course. In addition, we would like you to have have done the lab experiment which you are writing a package for, but recognize this may not always be possible, so we only require that you familiarize yourself with that experiment.

If you think you are able to contribute, then the steps you should take are:
 * 1) Tell us what experiment you want to write a data-analysis package for. (More info on what this should include can be found below.)
 * 2) Add yourself to the working list of projects, and add a short description of the main functions and scripts which you aim to write. Keep it updated so we can track your progress as you work. The project list is a document on google drive, and can be found here. (URL: http://tinyurl.com/pyyo56e)
 * 3) When you have "finished" your MATLAB package, write as many (useful) comments in it as you possibly can. The aim is that a First Year Undergraduate would be able to understand and modify the code to suit their own purposes! This might be unrealistic, but a First Year should be able to read a textbook on MATLAB and then understand the code if nothing else. One of the key flaws oflsfr26.m (the least-squares package provided by the University) is that is is horrendously complicated and none of us have been able to really understand it and modify it to suit our needs, hence we wrote a "better" one.
 * 4) Write a documentation file for your package (in word or libreoffice writer etc) and export it to pdf. It should include all relevent information for your package. We will write some additional ones for creating csv data files and general programming in MATLAB etc.
 * 5) Show us what you have done. (Show both Greg Knowles and Ed Bird, we are contactable via Facebook, as we will try our best to provide you good feedback and suggestions for improvement.
 * 6) Implement any improvements, check for bugs as best you can, update the documentation. Repeat this cycle untill we and you are happy enough to go to the next stage. This process is important as we want a robust as possible method for checking everyones work. (Including our own, we will need your help for that too.)
 * 7) Take your work to Neil Jackson, who is the current chair of lab. He will put it though more rigerous testing and suggest improvements
 * 8) Repeat.
 * 9) When what you have produced is a really good piece of work, is easy to use and understand, and will help the next generation of students, then it will be given the stamp of approval by the department. These final steps are not finalized yet. We will add more details in the future.

What Should Be In A Data-Analysis Package?
We aren't exactly sure... yet...

But, taking a look at the lsfr package which Ed Bird has written may help give you ideas and guide you in the right direction.

There are several key points we want to emphasise. We want you to produce something which you will find or have found useful in the lab. As a general rule, if you wrote some MATLAB code which helped you with your data analysis for a particular experiment then the chances are someone else will find it useful too.

Do this:
 * "Black box" code. This ideom is that the code (MATLAB function, script, etc) acts as a black box. You shouldn't need to know how it works on the inside, although it's good if you explain using comments and in the documentation, that way students can learn from your work. It should take some sensible input and output some results in a sensible array.
 * Modular code. This means it can be used in different configurations. An example is, don't write an LSFR routine which takes a data-file as the input argument. If you do this it can only be used on files which are formatted in a specific way. Write one which takes input data as arrays then also write a function to load data into arrays from a file which must be formatted as you decribe in the documentaton. That way you can also write a script which first loads the data file into some arrays and then processes it. This is modular code... The studnet can easily "chop off" the loading-from-datafile process if they don't need it! Different areas of functionality of your program should be split into different functions accordingly. (Loading from file is a different process from a least-sqaures fit.)
 * Documenation. An additional PDF file explaining how your code works and how to use it including examples. No student should be left frustrated by us telling them that a particlular package is available to help them but then finding they do not understand how to use it.
 * Code that can be used in scripts and from the MATLAB command line to create completely automated data-processing.
 * Error checking but don't get stupid. It's not worth adding 1000 lines of code to check for every possibility of the user using the code incorrectly. That will make things hard to manage and difficult to edit. Obvious things should be checked for.
 * Provide your package with documentation and all relevent files including example data files when appropriate in a .zip file. This makes it easy to download, it will come as a "complete package", and smaller filesizes are good.

Do NOT do this:
 * GUI's! (Graphical User Interfaces) These are slow as they involve lots of mouse clicks from the user to get stuff operating and that is time consuming, the exact opposite of what we want. Yes they may look nice and impressive, but they involve loads of lines of code and add unnesccery complication. What we want is a function you can just type the name of and hit enter and it will do stuff for you. Working in this way allows you to put code in a script to automate the whole process!
 * Printing loads of stuff to the command line! Displaying results to the user is a different process. So is plotting graphs. We WANT you to include code to plot relevent graphs, but do NOT want you to wrap the whole thing in one function. If the user wants to plot a graph, then great, get them to run the plotGraph function, that way they get a choice.
 * No poppy-uppy dialogue boxes. No one cares if chi-square is 5 times larger than realistically expected. The student will find that out when they run the printChiSquare function.