Welcome to FarSeer-NMR Documentation!¶

FarSeer-NMR¶

Attention Attention Attention

We are currently rewriting Farseer-NMR towards version 2.

Version 1 is still functional and working, though not much supported apart from minor bugs. You can download the latest stable version, v1.3.5, on the releases tab, or visit the complete version 1 code and its documentation in version 1 branch) on GitHub.

Our original publication is available at JBioMolNMR), cite us if you use Farseer-NMR for your research, regardless of which version you use.

Please note that the master branch) currently hosts the development of version 2, which is UNFINISHED software; again, please, refer to version 1 for a stable and functional release.

Farseer-NMR runs purely on volunteer work without any official assigned funds. All help is welcomed, engage with us)!

Attention Attention Attention

https://raw.githubusercontent.com/Farseer-NMR/FarSeer-NMR/master/docs/img/GitHub_Farseer-NMR_Workflow.png

A Python written, multi-platform and fully community-driven suite to analyse datasets of peaklist files extracted from multivariable series of Biomolecular Nuclear Magnetic Resonance (NMR) experiments.

With Farseer-NMR, you have:

Automatic analysis of large and multivariable NMR peaklist files datasets
Peaklist parsing and treatment
Identification of _missing_ and _unassigned_ residues
Automatic calculation of NMR parameters
Comprehensive organization of the output
Large suite of publication-ready plotting templates
Full traceability via Markdown) formatted log file.

You can read now through the contents bellow.

Contents¶

Installation¶

To install FarSeer-NMR version 2: …

Usage¶

To use FarSeer-NMR version 2…

Contributing¶

Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given. You can contribute from the scope of an user or as a core Python developer.

Reporting and Requesting¶

Bug reports¶

When reporting a bug please use one of the provided issue templates if applicable, otherwise just start a blank issue and describe your situation.

Documentation improvements¶

FarSeer-NMR could always use more documentation, whether as part of the official FarSeer-NMR docs, in docstrings, or even on the web in blog posts, articles, and such. Write us a documentation issue describing what you would like to see improved in the documentation, and if you can do it just Pull Request your proposed updates.

Feature requests and feedback¶

The best way to send feedback is to file an issue at https://github.com/Farseer-NMR/FarSeer-NMR/issues/new/choose using the feature template.

If you are proposing a feature:

Explain in detail how it would work.
Keep the scope as narrow as possible, to make it easier to implement.
Remember that this is a volunteer-driven project, and that code contributions are welcome :)

Code Development¶

To contribute to the development of FarSeer-NMR:

Fork the FarSeer-NMR repository.

Clone your fork to your local machine:

git clone https://github.com/YOUR-USER-NAME/FarSeer-NMR.git <destination folder>

Set up a new Python environment for the development of FarSeer-NMR so that the development version does not conflict with the production installation.

3.1 If you use Anaconda as your Python package manager do:

conda env create -f requirements_conda.yml

3.2 If you are using PyPI as your package manager follow this instructions.

Remember to activate the new environment before proceeding to the installation, with Anaconda: conda activate farseernmrdev.
Install FarSeer-NMR in the development mode, from within your fork folder:
```
python setup.py develop
```

This ensures that the FarSeer-NMR version running in your development environment is the source in your git folder.

FarSeer-NMR relies on tox to orchestrate testing environments, ensuring correct collaborative development, install tox:
```
# with Anaconda
conda install -c conda-forge tox

# with PyPI
pip install tox
```

Create a branch for local development:

git checkout -b name-of-your-bugfix-or-feature

5.1 Now you can make your changes locally.

When you’re done making changes run all the checks and docs builder with tox one command:
```
tox
```

6.1. If all tests pass you are set to go :-)``

Commit your changes and push your branch to your FarSeer-NMR fork on GitHub:

git add .
git commit -m "Your detailed description of your changes."
git push origin name-of-your-bugfix-or-feature

Submit a pull request through the GitHub website.

To keep you fork repository updated with the main repository latest changes:

# move to the master branch
git checkout master

# add a reference to the upstream repository
# this is the main FarSeer-NMR repository
# you only have to do this once
git remote add upstream https://github.com/Farseer-NMR/FarSeer-NMR

# fetch the latest code from the main repository
git fetch upstream

# merge those changes to your master branch
git pull upstream master

# push to you online repository the new changes
# so that your fork synchronizes with the main
git push origin master

To continue developing a new feature just repeat from steps 5.

Pull Request Guidelines¶

If you need some code review or feedback while you’re developing the code just make a pull request.

For merging, you should:

Include passing tests (run tox) 1.
Update documentation when there’s new API, functionality etc.
Add a note to CHANGELOG.rst about the changes.
Add yourself to AUTHORS.rst.

1

If you don’t have all the necessary python versions available locally you can rely on Travis - it will run the tests for each change you add in the pull request.

It will be slower though …

Tips¶

You can run individual test environment with tox, for example, to test lint:

tox -e check

to test documentation:

tox -e docs

to perform coverage-reported tests:

tox -e py38

Continuous Integration¶

This project follows Continuous Integration (CI) good practices (let us know if something can be improved). As referred in the previous section, testing environment is provided by tox. All tox testing environments run on Travis-CI; there, we check for code style, code quality, documentation, tests and test coverage. If you want to know more, tox testing configuration is defined in the tox.ini file.

Citing¶

Thanks for using Farseer-NMR!

If you are using Farseer-NMR, or any of its components, to analyze your NMR peaklist data, please cite our original article:

Teixeira, J.M.C., Skinner, S.P., Arbesú, M., Breeze, A.L., Pons, M. J Biomol NMR (2018) 71:1, 1-9. DOI 10.1007/s10858-018-0182-5)

Publications citing Farseer-NMR¶

Miguel Arbesú, MiquelPons. Integrating disorder in globular multidomain proteins: Fuzzy sensors and the role of SH3 domains. Archives of Biochemistry and Biophysics 2019, 677, 108161 https://doi.org/10.1016/j.abb.2019.108161.
Luca Mureddu, Geerten W. Vuister. Simple high‐resolution NMR spectroscopy as a tool in molecular biology. The FEBS Journal 2019, 286, issue 11, p2035 https://doi.org/10.1111/febs.14771.
Teixeira, J.M.C.; Fuentes, H.; Bielskutė, S.; Gairi, M.; Żerko, S.; Koźmiński, W.; Pons, M. The Two Isoforms of Lyn Display Different Intramolecular Fuzzy Complexes with the SH3 Domain. Molecules 2018, 23, 2731. https://doi.org/10.3390/molecules23112731)
Arbesú, M.; Iruela, G.; Fuentes, H.; Teixeira, J.M.C.; Pons, M. Intramolecular fuzzy interactions involving intrinsically disordered domains. Front. Mol. Biosci. 2018, 5, 39. DOI 10.3389/fmolb.2018.00039)
Arbesú, M. et al. (2017) The Unique Domain Forms a Fuzzy Intramolecular Complex in Src Family Kinases. Structure 25, 630–640.e4. 10.1016/j.str.2017.02.011)
Marimon, O. et. al. (2016). An oxygen-sensitive toxin–antitoxin system. Nature Communications, 7, 13634. https://doi.org/10.1038/ncomms13634)
Bijlmakers, M.-J., et.al. (2015) A C2HC zinc finger is essential for the RING-E2 interaction of the ubiquitin ligase RNF125. Scientific Reports, 6, 29232. https://doi.org/10.1038/srep29232)

Farseer-NMR on Google Citations)

Authors¶

All time complete authors contribution list..

Version 2 (under development)¶

Version 1¶

Version 1 development cycle spans from initial implementations to JBioNMR publication.

Acknowledgments¶

The Farseer-NMR Project wants to acknowledge to following people for their contributions to the project:

Susana Barrera-Vilarmau ([ORCID 0000-0003-4868-6593](https://orcid.org/0000-0003-4868-6593)): beta-tester, data provider, plot suggestions.
Jamie Ferrar, [Artistic Systems](https://twitter.com/artisticsystems): for providing the UI branding.
[João P.G.L.M. Rodrigues](https://github.com/JoaoRodrigues): for all the years of coding discussions and mentorship, and in particular for the help in setting the Farseer-NMR organization profile on GitHub.
Héctor Fuentes: intensive beta-tester, specially for the Windows version.
To all the users and participants of the Farseer-NMR workshops, thanks for your feedback, opinions, testing, interest and patience. Your contribution is definitively making Farseer-NMR growing bigger and robust! Special thanks to:
- [Micael Silva (Nova University of Lisbon)](https://www.researchgate.net/profile/Micael_Silva)
- [Wouter Elings (Leiden University)](https://www.universiteitleiden.nl/en/staffmembers/wouter-elings#tab-1)

License¶

The entire Farseer-NMR project is distributed with no liability and is licensed under the GPL-3.0.