Standardized README to Markdown format

README.md

@@ -0,0 +1,61 @@
+# Striatum Model from Humphries, Wood and Gurney (2009)
+
+This is a complete set of code required to run and analyse the striatum model from Humphries, Wood and Gurney (2009). The code is freely available for study and modification. Please cite the original sources. For questions and assistance contact:  
+m.d.humphries@shef.ac.uk or drmdhumphries@gmail.com
+
+---
+
+## Top-level Files:
+
+- **Experiment_RandomInput.m:** the top-level function that runs the model; this contains a selection of frequently changed parameters
+- **StriatumNetworkParameters.m:** the complete specification of the model; a few of the parameters set here are overwritten in Experiment_RandomInput.m
+- **RunSimulation.m:** function called by Experiment_RandomInput.m to handle passing the parameters to the MEX file that runs model simulation
+- **checkStriatumInputs.m:** ensures that all parameters are of the right class and type for handing to the MEX function (called by RunSimulation.m)  
+
+### ./CreateNetwork (folder):
+
+- **BuildStriatumNetwork.m:** builds the network model according to the specified parameters (called by StriatumNetworkParameters.m); uses the probability of intersection functions supplied by the 4 .mat files in this folder
+- **GetNeuronPositions.m:** puts all neurons in their 3D positions, ensuring that none are closer than the minimum set distance (called by BuildStriatumNetwork.m)  
+
+### ./Simulation (folder):
+
+This contains the MEX files and source C code for the simulation engines that run the model. By default the simulation uses the **striatum_RK2** MEX file, solving the ODEs using the midpoint method (aka 2nd order Runge-Kutta). The original Euler-method solver is included as **striatum.cpp**. We have also included the alternative **striatum_ZOH.cpp** option, which solves the model using a zero-order hold solution method (from Humphries & Gurney, 2007). The latter is useful for double-checking the results of the RK2 method. Simply swap the function call in RunSimulation.m.
+
+The RK2 method MEX files are provided compiled for 32-bit (.mexw32) and 64-bit (.mexw64) Windows, and for 64-bit (.mexa64) Linux systems. The other methods' MEX files are compiled for 64-bit (.mexa64) Linux. We strongly recommend that you recompile the MEX code from the source C++ for your platform.
+
+### ./Analyses (folder):
+
+- **firing_stats_solo.m:** a quick analysis of the firing properties of a simulation
+- **cluster_words_winsize.m:** does the first pass of the clustering analysis detailed in Humphries et al 2009, across the range of specified binsizes
+- **retained_graph_properties.m:** takes the highest-scoring binsize from cluster_words_winsize.m, and tests a range of thresholds: the clustering with the highest beta score from this second stage was the one generally reported in the paper. The second half of the code extensively analyses the network of the anatomy model, attempting to relate the groups found by the clustering to some properties of the anatomy.
+- **firing_stats.m:** called by retained_graph_properties.m, is a simplified version of firing_stats_solo.m  
+
+### ./Tools (folder):
+
+Helper functions for the analyses. **Multileadevsplit.m** is the main function for the graph-cut clustering method.
+
+---
+
+## Notes:
+
+1. The solution method used in this code is RK2, not Euler as in the paper; the effect of this is to improve the stability of the numerical solution, and allow us to use an order of magnitude larger time-step to speed up the simulations (dt = 0.1ms in the current code).
+
+2. This code represents the state-of-the-art of our striatal model after completion of the Neural Networks paper in 2009, and is a complete model. Since then we have improved components of the model in further publications, but not yet published a combined overhaul. These improvements are:  
+   (a) an updated model of dopamine's effects on the MSN (Humphries, Lepora, Wood & Gurney, 2009b)  
+   (b) an updated model of the striatal anatomy model (Humphries, Wood & Gurney, 2010); the code for this model will also be available on ModelDB, and from the authors  
+
+---
+
+## References:
+
+Humphries, M. D. & Gurney, K. (2007) Solution methods for a new class of simple model neurons. *Neural Computation*, 19, 3216-3225. [PDF copy included with code]
+
+Humphries, M. D., Wood, R. & Gurney, K. (2009) Dopamine-modulated dynamic cell assemblies generated by the GABAergic striatal microcircuit *Neural Networks*, 22, 1174-1188. [PDF copy included with code]
+
+Humphries, M. D.; Lepora, N.; Wood, R. & Gurney, K. (2009b) Capturing dopaminergic modulation and bimodal membrane behaviour of striatal medium spiny neurons in accurate, reduced models. *Frontiers in Computational Neuroscience*, 3, 26. Download at: [http://dx.doi.org/10.3389/neuro.10.026.2009](http://dx.doi.org/10.3389/neuro.10.026.2009)
+
+Humphries, M. D., Wood, R. & Gurney, K. (2010) Reconstructing the three-dimensional GABAergic microcircuit of the striatum. *PLoS Computational Biology*, in press.
+
+---
+
+2025-06-02: Converted README to Markdown.