{ "info": { "author": "Kale Kundert", "author_email": "kale@thekunderts.net", "bugtrack_url": null, "classifiers": [ "Development Status :: 2 - Pre-Alpha", "Intended Audience :: Science/Research", "License :: OSI Approved :: GNU General Public License v3 (GPLv3)", "Programming Language :: Python :: 3.6", "Topic :: Scientific/Engineering" ], "description": ".. image:: brand/logo.png\n :align: center\n\n*Ex memoriam* (or exmemo for short) is a tool for organizing a scientific \nproject and keeping a lab notebook, for people who like using the command-line. \nAny files associated with the project are kept in a straight-forward but \nwell-thought-out directory tree that you're meant to interact with in the \nshell, and that's also a git repository. The lab notebook is comprised of \nplain text files (in the restructured text format) that you can write using \nyour favorite editor (which should be vim \ud83d\ude03). These files are rendered to \nHTML by Sphinx (the same tool that is used to document most python projects) \nand can either be viewed locally or uploaded to the internet. Exmemo also \nprovides commands that let you easily refer to files in different parts of the \nproject without having to type full paths, and installs a handful of \nrestructured text directives to address some common lab notebook formatting \nneeds. Finally, both exmemo and Sphinx can be heavily extended using python, \nso you can make your notebook work exactly how you want it to.\n\n.. image:: https://img.shields.io/pypi/v/exmemo.svg\n :target: https://pypi.python.org/pypi/exmemo\n\n.. image:: https://img.shields.io/pypi/pyversions/exmemo.svg\n :target: https://pypi.python.org/pypi/exmemo\n\n.. image:: https://img.shields.io/travis/kalekundert/exmemo.svg\n :target: https://travis-ci.org/kalekundert/exmemo\n\nInstallation\n============\nInstall using pip::\n\n $ pip install exmemo\n\nUsage\n=====\nAt the moment there isn't much online documentation, but the command-line help \nsystem should have any information you need::\n\n $ exmemo --help\n Manage a project directory.\n\n Usage:\n exmemo [...]\n exmemo (-h | --help)\n exmemo --version\n\n Commands:\n init: Create a directory layout for a new project.\n new: Create a new experiment with a blank notebook entry.\n edit: Open the notebook entry for the given experiment in a text [...]\n open: Open a new terminal cd'd into the given experiment.\n build: Render the lab notebook to HTML using Sphinx.\n browse: Open the rendered lab notebook in a web browser.\n show: Display the given protocol.\n print: Print the given protocol.\n archive: Save the protocol to a date-stamped text file that can be [...]\n sync: Import data into the project from any available source.\n link: Make a symbolic link to the indicated data file.\n project: Manage the entire project.\n note: Keep notes on your day-to-day experiments.\n protocol: Manage, display, and print protocols.\n data: Interact with data files.\n config: Get and set configuration options.\n debug: Print information that can help diagnose problems with exmemo.\n\nYou can also get help for individual subcommands::\n\n $ exmemo note --help\n\nExample\n=======\nIf you're just getting started with exmemo, the first step is to create a new \nproject directory::\n\n $ exmemo init \"Silly Walks\"\n\nThis command takes the name of the project in title-case. It'll prompt you for \nsome more information, then create and fill in a project directory for you. \nThe project will have the following directories:\n\n``analysis/``\n A python package containing code used for data analysis. By virtue of being \n a package, this code can be run from anywhere in the project.\n\n``data/``\n A single directory for any data file you collect. Data files that are \n relevant to a particular experiment can be symlinked into the notebook \n directory.\n\n``documents/``\n A directory for presentations, papers, and the like.\n\n``notebook/``\n A Sphinx directory with separate directories for each experiment you carry \n out. Each experiment is meant to ask and answer a single question, whether\n that takes a single day or several months.\n\n``protocols/``\n A directory for protocols, which can be text files, python script, Excel \n files, Word documents, whatever.\n\nLet's start by creating a new entry (called an \"experiment\") in our lab \nnotebook::\n\n $ exmemo note new \"Large step with half twist\"\n\nThis will create a subdirectory called ``20171210_large_step_with_half_twist/`` \nin the ``notebook/`` directory. It will also create a restructured text file \nin that directory and automatically open it in your editor. (You can control \nwhich editor is used either by setting the $EDITOR environment variable or by \nediting one of exmemo's config files; see ``exmemo config --help``.) One of \nthe ideas behind exmemo is that files related to a particular experiment --- \nnotebook entries, raw data, analysis scripts, figures, etc. --- should be \nstored together. That's what this subdirectory is for.\n\nWhen you later want to edit the notebook entry again, you can do so from \nanywhere in the project directory with the following command::\n \n $ exmemo note edit twist\n\nNote that you can specify the experiment by giving just part of its name. If \nyou give a substring that matches multiple experiments, you'll be asked which \none you meant. If you don't specify an experiment at all, the most recent one \nwill be opened.\n\nSimilarly, you can launch a new terminal that's already cd'd into a particular \nexperiment directory using this command::\n\n $ exmemo note open twist\n\nWhen you want to recompile the HTML pages for your notebook, run this command::\n\n $ exmemo note build\n\nNow lets say that we're about to go into lab and actually do an experiment. We \ncan start by printing out a paper copy of the protocol we want to follow. (I \nlike doing this because I can take notes as I'm working on the paper, then \ntranscribe any that are significant back into my notebook when I'm done.)::\n\n $ exmemo protocol print treadmill\n\nAgain the argument to this command (\"treadmill\") can just be a substring, but \nthis time exmemo will look for matches in your ``protocols/`` directory. You \ncan also tell exmemo to look in directories outside your project (i.e. if you \nhave protocols that are shared between projects), see ``exmemo protocols ls \n--help`` for details).\n\nWe'd also like to make a copy of this protocol in the experiment subdirectory \nwe made, so we can include the protocol in our lab notebook entry. To do this, \nfirst launch a terminal that's cd'd into the experiment subdirectory::\n\n $ exmemo note open twist\n\nThen run the following command to make a date-stamped copy of the protocol::\n\n $ exmemo protocol archive treadmill\n\nText protocols can be included in a restructured text document using the ``.. \nliteral-include::`` directive, and anything else can be included using the \n``:download:`` role.\n\nExmemo can also show you a protocol without printing it::\n\n $ exmemo protocol show treadmill\n\nWhat exactly this command does depends on what type of file the protocol is. \nText files will simply be printed to the terminal, python scripts will be \nexecuted, documents (like \\*.doc and \\*.xls) will be opened in libreoffice, and \nPDF files will be opened in your PDF viewer. You can use the setuptools plugin \nsystem to provide plugins for new filetypes, or to override the behaviors of \nthe existing ones.\n\nNote that there isn't a command to create a new protocol. Protocols are just \nregular files in the ``protocols/`` directory, so just create them however you \nwould normally `create files `_.\n\nProtocol in hand, we do our experiment and get some data. Let's say this data \nis on our USB drive. Exmemo has a command to automatically sync data from \ndifferent sources into the project, but first we need to configure it. So we \nput the following lines in the ``.exmemorc`` file in the root directory of the \nproject::\n\n [[data]]\n type = 'usb'\n src = '~/usb/treadmill'\n mountpoint = '~/usb'\n\nThis specifies that exmemo should look for data in the ``~/usb/treadmill`` \ndirectory of your USB drive, which is mounted as ``~/usb``. Any data the \nexmemo finds will be rsync'd into the ``data/`` directory of the project. \nExmemo will also try to automatically mount and unmount the USB drive, if it \ndoesn't seem to be mounted when you run the command.\n\nNow we can sync our data, so we plug in the USB drive and run the following \ncommand::\n\n $ exmemo data sync\n\nIf we want to include this data in our notebook or do some analysis on it, we \nshould symlink it into the subdirectory we made for this experiment. (Again, \nthis keeps all the files relevant to a particular question in one place.) To \ndo this, the first step is to fire up a terminal that's cd'd into the \nexperiment subdirectory::\n\n $ exmemo note open twist\n\nThen run the following command to symlink to some data::\n\n $ exmemo data link \n\nAgain, you can specify which file you're interested in using just a substring. \nExmemo will search the ``data/`` directory looking for matching files, and will \nask you if there's any ambiguity. You can include images in your restructured \ntext files using the ``.. figure::`` directive, and any other type of data can \nbe included using the ``:download:`` role.\n\nWhy initially copy the data into the ``data/`` directory, just to symlink it \ninto an experiment subdirectory later? There are a couple reasons. First, \ndata files are often large and binary, so keeping them in one places makes it \neasier to handle them specially when doing backups or making commits. Second, \nnot every data file ends up in an experiment. Some data just doesn't need to \nbe analyzed and displayed in your notebook. Other data are just not associated \nwith any experiment (i.e. gels from routine cloning).\n\nExmemo has some other features as well, but this covers the main workflow. \nAgain, the command-line help messages are pretty good, so start there if you're \nlooking for more details.\n\nCollaborating\n=============\nIf you want other people to be able to read your notebook without necessarily \nbeing able to edit it, the best option is to publish the HTML files generated \nby Sphinx on the internet somewhere. If you don't mind your files being public \n(or are willing to pay to keep them private), ReadTheDocs is a nice service for \nthis. Otherwise it's not to hard to setup a webserver that uses Apache \nauthentication to keep your files private.\n\nIf you want other people to be able to read and edit your notebook, the best \noption is to use git. The project directory is already a git repository, so \nyou just need to push it to GitHub and add anyone you want to work with as a \ncollaborator. As before, you can either pay GitHub or setup your own git \nserver if you want to keep your files private (although GitHub is often willing \nto give free private repositories to academic researchers).\n\nAliases\n=======\nThe exmemo commands are rather verbose, which is not ideal for things you want \nto be typing all the time. There are shortcuts for some of the most common \ncommands (e.g. ``exmemo edit`` instead of ``exmemo note edit``) and you can \nmake any command a little shorter by only typing the first few letters of each \nsubcommand (i.e. ``exmemo ed`` instead of ``exmemo edit``), but it's still not \nideal. For that reason, I use the following set of shell aliases::\n\n alias en='exmemo note new'\n alias ee='exmemo note edit'\n alias eo='exmemo note open'\n alias eb='exmemo note build'\n alias el='exmemo note ls'\n alias ew='exmemo note browse'\n alias eww='exmemo note browse -w'\n alias eps='exmemo protocol show'\n alias epp='exmemo protocol print'\n alias epe='exmemo protocol edit'\n alias epl='exmemo protocol ls'\n alias epr='exmemo protocol archive'\n alias edy='exmemo data sync'\n alias edk='exmemo data link'\n alias edg='exmemo data gel'\n\n function ed () {\n d=$(exmemo note directory \"$@\")\n [ $? = 0 ] && cd $d || echo $d # Don't try to cd if something goes wrong.\n }\n\nContributing\n============\nExmemo is a very new project. I'm sure there are still lots of bugs and use \ncases I didn't consider. Both `pull requests \n`_ and `bug reports \n`_ are very welcome.", "description_content_type": "", "docs_url": null, "download_url": "", "downloads": { "last_day": -1, "last_month": -1, "last_week": -1 }, "home_page": "https://github.com/kalekundert/exmemo", "keywords": "", "license": "", "maintainer": "", "maintainer_email": "", "name": "exmemo", "package_url": "https://pypi.org/project/exmemo/", "platform": "", "project_url": "https://pypi.org/project/exmemo/", "project_urls": { "Homepage": "https://github.com/kalekundert/exmemo" }, "release_url": "https://pypi.org/project/exmemo/0.2.0/", "requires_dist": null, "requires_python": "", "summary": "", "version": "0.2.0" }, "last_serial": 5308263, "releases": { "0.0.0": [ { "comment_text": "", "digests": { "md5": "b7a6111c6d48d82206f227bc487ef44a", "sha256": "21cd7905f6f70be1a6e56aee63f9f2317eaa0aa7a7b4efe93e97e60596ad24f0" }, "downloads": -1, "filename": "exmemo-0.0.0.tar.gz", "has_sig": false, "md5_digest": "b7a6111c6d48d82206f227bc487ef44a", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 19821, "upload_time": "2017-12-07T21:53:18", "url": "https://files.pythonhosted.org/packages/9f/8a/c88349bc7406387ac19bcedba96db24f09c2baea267f701daddec97def1a/exmemo-0.0.0.tar.gz" } ], "0.1.0": [ { "comment_text": "", "digests": { "md5": "7b27afaea4362aefb60d033f228c66c4", "sha256": "1cfc420df860b529a731054fe4c3f8d9bfd9d257dcc6e2b38b6c04c728e41ddd" }, "downloads": -1, "filename": "exmemo-0.1.0.tar.gz", "has_sig": false, "md5_digest": "7b27afaea4362aefb60d033f228c66c4", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 50428, "upload_time": "2017-12-11T17:25:10", "url": "https://files.pythonhosted.org/packages/9a/20/652b02ed917b9039cb0a6ddacaa7b3f08bdf064f836f15e8061b74d57bf2/exmemo-0.1.0.tar.gz" } ], "0.2.0": [ { "comment_text": "", "digests": { "md5": "f05ff30df6aa411d734d275d2210de2b", "sha256": "983317393fb7e304f2eb8ebd0dc338f1f40a14b471d6cf18f2366f02b3d8df0e" }, "downloads": -1, "filename": "exmemo-0.2.0.tar.gz", "has_sig": false, "md5_digest": "f05ff30df6aa411d734d275d2210de2b", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 56002, "upload_time": "2019-05-23T16:34:21", "url": "https://files.pythonhosted.org/packages/f2/4f/ac6828c236251a45e9b76e6ca9ccbbebc8ae431bfe569d424f8c2b72ee0c/exmemo-0.2.0.tar.gz" } ] }, "urls": [ { "comment_text": "", "digests": { "md5": "f05ff30df6aa411d734d275d2210de2b", "sha256": "983317393fb7e304f2eb8ebd0dc338f1f40a14b471d6cf18f2366f02b3d8df0e" }, "downloads": -1, "filename": "exmemo-0.2.0.tar.gz", "has_sig": false, "md5_digest": "f05ff30df6aa411d734d275d2210de2b", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 56002, "upload_time": "2019-05-23T16:34:21", "url": "https://files.pythonhosted.org/packages/f2/4f/ac6828c236251a45e9b76e6ca9ccbbebc8ae431bfe569d424f8c2b72ee0c/exmemo-0.2.0.tar.gz" } ] }