|
| 1 | +# Style Guide for Projects in the MLAI |
| 2 | + |
| 3 | + |
| 4 | +## Well before a publication: |
| 5 | + |
| 6 | +Please see our overall guide on code & project formatting [here](https://github.com/AdaptiveMotorControlLab/WorkspaceTemplate/blob/main/README.md). |
| 7 | + |
| 8 | +### Main Principles 🔨 Organize your code & data : |
| 9 | +- For experimental and ML projects, please use [DataJoint/databases](https://www.datajoint.com/) |
| 10 | +- Be sure you work under a lab repo, typically called "https://github.com/AdaptiveMotorControlLab/YourName_workspace". |
| 11 | +- For larger projects (DLC, CEBRA, ExperimentalPipelines, you should be sure your "final" work gets into a pipeline; talk to Mackenzie about this) |
| 12 | +- Lab Specific: please check the [CommonHelperCode](https://github.com/AdaptiveMotorControlLab/CommonHelperCode) for useful tips & scripts, and contribute your own! |
| 13 | + |
| 14 | +### Main Principles 🚧 Format your code & documentation: |
| 15 | +- In the lab we use the [Google Style Guide](https://google.github.io/styleguide/pyguide.html) for code. Please review this. |
| 16 | +- In the lab we use the [semantic versioning of code](https://semver.org/). Please review this. |
| 17 | +- In the lab we use the code formatting we outline in the main README [here](https://github.com/AdaptiveMotorControlLab/WorkspaceTemplate/blob/main/README.md). |
| 18 | +- As soon as you start a repo, start a JupterBook! Please see [here](https://github.com/AdaptiveMotorControlLab/WorkspaceTemplate/blob/main/README.md), and this repo has the template. |
| 19 | + |
| 20 | + |
| 21 | + |
| 22 | +## Ready to write up your work and share your hard work, data, & code? |
| 23 | +Here is how to do so most efficiently with me. |
| 24 | + |
| 25 | +- 🚨 First, I recommend having a one-on-one so we can lay out the paper sketch, authors, data and code sharing plan together if not already done. |
| 26 | +- 📝 I ask that we use [overleaf](https://www.overleaf.com/project) for **manuscripts**! Please ask me to start a template to share with you. |
| 27 | +- 🗺 I ask we use [figma](https://www.figma.com/) for **figures**; you can start a free educational group (or ask me to start one). Please then link this in the paper basecamp group. |
| 28 | +- If you have a deadline (ICCV/NeurIPS, etc), you must have everything ready **1 week before the deadline** and schedule a meeting to go over it (see Timeline below). |
| 29 | + |
| 30 | +### How to organize this all with Basecamp: |
| 31 | +- 🔗 Please link the development code repo code in basecamp |
| 32 | +- 🔗 Please link the overleaf |
| 33 | +- 🔗 Please link the figma file |
| 34 | + |
| 35 | +Collectively, your basecamp project should look like this: |
| 36 | + |
| 37 | + |
| 38 | + |
| 39 | + |
| 40 | +## Styles for plots, figures, and how to produce them |
| 41 | +- We use `matplotlib` and `seaborn` in python. |
| 42 | +- **Every plot in a paper must be reproducible in a Jupyter Notebook**. This means it loads the data (from datajoint/ possible later figshare or zenodo), plots it, and saves it. |
| 43 | +- By the time we are ready to submit a paper, it must have a `AMCL\PaperName-figures` repo. |
| 44 | + - Here are examples from the lab: |
| 45 | + - CellSeg3D: https://github.com/C-Achard/cellseg3d-figures |
| 46 | + - CEBRA: https://github.com/AdaptiveMotorControlLab/CEBRA-demos |
| 47 | +- I really like the plots in [CEBRA](https://www.nature.com/articles/s41586-023-06031-6), which you can find here: https://github.com/AdaptiveMotorControlLab/cebra-figures |
| 48 | + |
| 49 | +### Example plotting style: |
| 50 | +- Here is an example, be sure to note the **font, size, broken axis, transparency output**, etc: |
| 51 | + |
| 52 | +```python |
| 53 | +plt.figure(figsize=(3.5, 3.5), dpi = 200) |
| 54 | +ax = plt.subplot(111) |
| 55 | + |
| 56 | +keys = ['cebra', 'pivae', 'autolfads', 'tsne', 'umap'] |
| 57 | +df = pd.DataFrame(synthetic_scores) |
| 58 | +sns.stripplot(data=df[keys] * 100, color="black", s=3, zorder=1, jitter=0.15) |
| 59 | +sns.scatterplot(data=df[keys].median() * 100, color="orange", s=50) |
| 60 | +plt.ylabel("$R^2$", fontsize=20) |
| 61 | +plt.yticks( |
| 62 | + np.linspace(0, 100, 11, dtype=int), np.linspace(0, 100, 11, dtype=int), fontsize=20 |
| 63 | +) |
| 64 | +plt.ylim(70, 100) |
| 65 | +ax.spines["right"].set_visible(False) |
| 66 | +ax.spines["top"].set_visible(False) |
| 67 | +ax.tick_params(axis="both", which="major", labelsize=15) |
| 68 | +ax.tick_params(axis = 'x', rotation = 45) |
| 69 | +ax.set_xticklabels( |
| 70 | + ['CEBRA', 'piVAE', 'autoLFADS', 'tSNE', 'UMAP'], |
| 71 | +) |
| 72 | +sns.despine( |
| 73 | + left=False, |
| 74 | + right=True, |
| 75 | + bottom=False, |
| 76 | + top=True, |
| 77 | + trim=True, |
| 78 | + offset={"bottom": 40, "left": 15}, |
| 79 | +) |
| 80 | +plt.savefig('figure1_synthetic_comparison.jpg', bbox_inches = "tight", transparent = True) |
| 81 | +plt.savefig('figure1_synthetic_comparison.svg', bbox_inches = "tight", transparent = True) |
| 82 | +``` |
| 83 | +#### THEN: 🚨 Put the SVG into figma, AND for the final versions, make a white axis page & versions 🙏: |
| 84 | + |
| 85 | +Modify by adding: |
| 86 | +```python |
| 87 | +for spine in ax.spines.values(): |
| 88 | + spine.set_color("white") |
| 89 | +ax.tick_params(colors="white") |
| 90 | +ax.yaxis.label.set_color("white") |
| 91 | +ax.xaxis.label.set_color("white") |
| 92 | +``` |
| 93 | + |
| 94 | + |
| 95 | +### Timeline Major Point: |
| 96 | + |
| 97 | +For conference submissions, all papers must be in final form 1 week prior to the deadline. |
| 98 | +There will be no exceptions going forward. |
| 99 | +This gives us needed time to reflect, refine writing, get some distance, and ask colleagues for feedback. |
| 100 | +It also gives us time to prepare the code submission, and potentially arXiv the work -- which is always preferred. |
| 101 | +We should not be submitting manuscripts to conferences we would not want publicly read! |
0 commit comments