From 56e78851fc0d474d9ba6d0950a9bffee95131823 Mon Sep 17 00:00:00 2001 From: "Thomas A. Christensen II" <25492070+MillironX@users.noreply.github.com> Date: Sun, 16 Feb 2020 14:45:39 -0800 Subject: [PATCH] Start README revisions --- README.md | 84 ++++++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 71 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index 265ca4f..99799c4 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,59 @@ -# beefblup +# [:cow:]: beefblup -:cow: :cow: :cow: +beefblup is an easy-to-use program for ranchers to calculate expected breeding +values (EBVs) for their own beef cattle. Why? It's part of my effort to +**\#KeepEPDsReal** -#### \#KeepEPDsReal +> **Notice:** beefblup for MATLAB and beefblup for Python are going away. I'm +> going to make changes here soon that will break the MATLAB version of +> beefblup, and I don't intend to update it anymore. (How many ranchers do you +> know that can afford MATLAB?) As for beefblup for Python, it never really got +> off the ground, and beefblup for Julia has superceded it. -MATLAB and Python scripts and Excel spreadsheets that can be used in conjunction to find breeding values for beef cattle. +## For Users + +### Installation + +#### Windows (My Platform) + +1. Press the **Windows Key** + **X**, and then press **A**, and select **Yes** +2. [Install Chocolatey](https://chocolatey.org/install) using the PowerShell + window that opened +3. Close PowerShell +4. Press the **Windows Key** + **X**, and then press **A**, and select **Yes** + (Again) +5. Type `choco install Julia -y` into PowerShell and press **Enter** +6. Close PowerShell once Chocolatey has finished +7. Download and unzip beefblup to somewhere you will remember it +8. Hold down the **Shift** key, and **right-click** in a blank space in the + "Julia" folder of beefblup +9. Click **Open PowerShell window here" +10. Type `julia install.jl` into PowerShell and press **Enter** +11. Close PowerShell once Julia has finished + +Why do you need Chocolatey? Because it allows you to access Julia (and therefore +beefblup) from the **Shift**+**Right-click** menu directly, without having to +worry about `cd` commands or editing your `%PATH%`. That's good, right? + +#### Mac + +I don't know. I can't afford one. If any of you super-privileged Apple snobs +out there run beefblup, please add proper instructions here and submit a pull +request. + +#### Debian/Ubuntu Linux + +TODO: Add instructions here. This is slightly complicated since there is no +Julia package in the main repositories, and I don't use Debian distros enough to +know where to find a third-party repos + +#### Fedora Linux + +TODO: Add instructions here. I have this info, but it's on the work computer. ## How to Use -1. Download the [Excel template](https://github.com/MillironX/beefblup/raw/master/Excel/Master%20BLUP%20Worksheet.xlsx) +1. Choose a spreadsheet appropriate to the trait you want to analyze from the `Excel` folder, and save it to your hard drive 2. Place your data into the structure described by the spreadsheet 3. If you wish to add more contemporary group traits to your analysis, replace or add them to the right of the Purple section 4. Open MATLAB @@ -20,17 +65,32 @@ MATLAB and Python scripts and Excel spreadsheets that can be used in conjunction cd beefblup-master/MATLAB beefblup ``` - + 6. Select the spreadsheet file you just placed your data into 7. Select a file that you would like to save your results to 8. Breeding values and contemporary group adjustments will be outputted to the file you selected -## Contributing +## For Programmers -I will gladly accept pull requests that acomplish any of the following: +### Development Roadmap -* Convert MATLAB scripts to Python - * The product must be able to be run from the native (non-python) terminal using only the default [Anaconda Python packages](https://anaconda.com/distribution) +| Version | Feature | +| ------- | ------------------------------------------------------------------- | +| v0.1 | Julia port of original MATLAB script | +| v0.2 | Spreadsheet format redesign | +| v0.3 | API rewrite (change to function calls instead of script running) | +| v0.4 | Add GUI for all options | +| v0.5 | Automatically calculated Age-Of-Dam, Year, and Season fixed-effects | +| v0.6 | Repeated measurement BLUP (aka dairyblup) | +| v0.7 | Multiple trait BLUP | +| v0.8 | Maternal effects BLUP | +| v0.9 | Genomic BLUP | +| v0.10 | beefblup binaries | +| v1.0 | [Finally, RELEASE!!!](https://youtu.be/Zd-up5EgoMw?t=5049) | + +I will gladly take input on the following: + +* Converting MATLAB scripts to Python * Optimizing code sections * Use triagonal shortcuts to generate the additive relationship matrix * Solve implicit forms of the mixed-model equation @@ -43,7 +103,7 @@ I will gladly accept pull requests that acomplish any of the following: * Creation of spreadsheets for additional traits * Creation of wiki pages to explain what each script does * The general rule is that **every** wiki page should be understandable to anyone who's passed high school algebra, while still being correct and informative - + Note that I intend to implement all of the items above eventually, but progress is slow since I'm learning as I go. @@ -55,8 +115,6 @@ If you are writing code, please keep the code clean: * For MATLAB, functions go in a separate file * Comments go before a code block: no inline comments -Bug reports and suggestions will be gladly taken on the [issues](https://github.com/MillironX/beefblup/issues) page. There is no set format for issues, yet, but please at the minimum attach a filled-out spreadsheet that demonstrates your bug or how your suggestion would be useful. - ## License Distributed under the 3-Clause BSD License