Skip to content

Commit

Permalink
Update documentation
Browse files Browse the repository at this point in the history
This is the beginning of adjusting the documentation to be better for
the PyPWA users. We'll be adding more documentation throughout the
summer as user's have confusion about how to use a certian function, or
to complete a specific function.

This also includes updated GitHub documents, so now we'll have templates
for issues, a contributors file, and an up to date readme.
  • Loading branch information
markjonestx committed Jun 2, 2020
1 parent 50aa0dd commit 008438b
Show file tree
Hide file tree
Showing 13 changed files with 180 additions and 304 deletions.
27 changes: 27 additions & 0 deletions .github/ISSUE_TEMPLATE/bug_report.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
---
name: Bug report
about: Create a report to help us improve PyPWA
title: ''
labels: ''
assignees: ''

---

**Describe the bug**
A clear and concise description of what the bug is.

**To Reproduce**
Steps to reproduce the behavior:

**Expected behavior**
A clear and concise description of what you expected to happen.

**System Information:**
- OS: [e.g. Redhat 7]
- Python Version:
- Anaconda, System, or Virtualenv:
- PyPWA Version:
- Personal Machine, JLab, or other (Explain):

**Additional context**
Add any other context about the problem here.
17 changes: 17 additions & 0 deletions .github/ISSUE_TEMPLATE/feature_request.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
---
name: Feature request
about: Suggest an idea for PyPWA
title: ''
labels: ''
assignees: ''

---

**Is your feature request related to a problem? Please describe.**
A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]

**Describe the solution you'd like**
A clear and concise description of what you want to happen.

**Additional information**
Add any other context or screenshots about the feature request here.
17 changes: 17 additions & 0 deletions .github/ISSUE_TEMPLATE/help-request.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
---
name: Help Request
about: Get help from us for your PyPWA use-case
title: ''
labels: ''
assignees: ''

---

**What is your use-case, what are you analyzing?**
A clear and concise description of what problem you're trying to solve.

**Describe in detail what you are having issues with.**
Are you having issues loading data? Are you getting unexpected results?

**Additional information**
Add any other context or screenshots about the feature request here.
1 change: 1 addition & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/)
using the supplied wave and resonance objects.
- Adds support for Numexpr to accelerate computation.
- Simulation can be done as two separate parts through PyPWA.simulate
- Github Templates to help users and developers contribute to PyPWA
### Changed
- Separate release tag from version info
- Package info is now stored in PyPWA.info
Expand Down
77 changes: 77 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,77 @@
# Contributing

Thank you for contributing to PyPWA! With the help of people like you,
we can make PyPWA a great Python based Partial Wave Analysis and High
Energy Physics toolkit.

## Where to start?

You don't need to have any physics or programming experience to start
contributing to PyPWA. If you are a physists who has never written code,
a software developer with little physics background, or even a new
student with little experience in either, we have projects that you can
help us with.

If you want to help, or get help, lets us know in the Issues section!

## Filing issues, Feature Requests, or requesting help

If you have a feature request, discovered a bug, a flaw in the
documentation, or a use-case where the toolkit runs slowly, please let
us know in the Issue tracker on Github.

When you are making a new issue on Github, you'll have a choice between
filing a bug report, feature request, or help request. Select which one
you want, and we will get reply as quickly as we can.

## Developing for PyPWA

PyPWA follows the PEP standard, which if you're using PyCharm the IDE
should help you conform to the format if you're new to it. We also
write all our documenation in numpydoc.

Any functions or objects that are meant to be used by the users should
be imported directly into PyPWA/__init__.py and should be thoroughly
documented including examples. If it's an internal function however, it
should be moreso documentated in the code itself.

### Forking and branching

If you are working directly with us, and have access to the repository,
you will be forking all your branches off of the `development` branch.
All your additions will happen on that branch, and after your branch
passes reviews, you're branch will be merged into the `development`
branch to be included in the next release.

If you are a contributor from outside Jefferson Lab, please fork PyPWA,
make your changes to the `development` branch, and then submit a pull
request. We'll review your pull request, suggest changes, and then
accept your pull request.

### Running the test suite

We use PyTest for our testing. All code contributed to PyPWA should have
tests included in the fork or branch before it's merged into
`development`. This is so that we can continue to deliver as stable of
an experience as possible. We have no strict rules on the tests, but
please do your best to keep them short and concise.

### Merging or combining branches (Core Devs Only)

When you are combining a feature, fix, or documentation branch into
PyPWA, you squash all commits into a single commit, and then merge into
`development` with complete patch notes. The command to do this from a
standard machine is `git merge --squash`. This is to prevent the git
log from being polluted with small uninformative commits, and to keep
tracking changes concise.

### Creating a release (Core Devs Only)

When preparing for a release, a release branch for the new release
should be forked off of master, and all it's documentation should be
updated for the new release version. This should also be used as a final
attempt to catch any bugs that may have yet to been patched. Once all
bugs are patched, documentation is updated, tests passing, that is when
you would merge the branch into both master and development without
squash. It is desirable to maintain the full git log from development
when merging into master.
68 changes: 32 additions & 36 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,61 +4,57 @@ PyPWA [![Build Status](https://travis-ci.org/JeffersonLab/PyPWA.svg?branch=devel
A python based software framework designed to perform Partial Wave and
Amplitude Analysis with the goal of extracting resonance information from
multi-particle final states.
Is constantly tested to work with Python Version 3.7
Is constantly tested to work with Python Version 3.7+

Has support for multiple likelihoods, including:

<!--Has support for multiple likelihoods, including:
- Extended Log Likelihood
- Standard Log Likelihood, Optionally Binned
- Binned ChiSquared Likelihood
- Standard ChiSquared Likelihood

You can even define your own likelihood, or calculate entirely without one
if you chose to do so!
-->
You can even define your own likelihood, or calculate entirely without one
if you chose to do so!


Currently being updated to PyPWA 3 (Summer 2019)
Currently being updated to PyPWA 3 (Summer 2020)
------------------------------------------------

There is an ongoing project for PyPWA to integrate various complex models
directly into PyPWA as well as decoupling interface logic from program
logic so that we may add a fully functioning GUI to the package.

Progress:
- Analysis programs:
- [X] pysimulate
- [ ] pyfit
- [ ] New interface needs to be written
- [ ] Model selection metadata needs to be finalized
- [ ] pyproject (replaces pythonPWA)
- [ ] Allow for work on large projects involving bins of data
- [ ] Handle multiple subprojects for different data and fit types
- [ ] Visualization for fits and data
- Data Programs
- [ ] PyMask
- [ ] Renamed to pydata
- [X] Able to both mask data and convert data between simple types
- [ ] pyhd5 (Pending title, partially in place)
- [ ] Rename to pyhd5 from pydata
- [X] Load data into hdf5 tables
- [X] Support multivariable binning inside the table
- [X] Optionally write data back from table
We're currently adding fixes and documentation as we prepare for an
official PyPWA 3 release! If you notice inconsistencies in our
documentation, or unusual slow-downs, please let us know in the issues!


Features
--------

Generic Fitting Tools
<!--
- PyFit

- Fitting
- Can fit to a log-likelihood, chi-square, or you can define your own
- Supports Binned Data
- Supports a quality factor per event -->
- PySimulate
- Easy to use Yaml based configuration
- A configuration builder, to walk you through the initial creation of
the configuration
- Supports a quality factor per event
- Simulation using Monte Carlo Rejection
- Easy to use Yaml based configuration for command line operation
- Jupyter Integration
- Supports using all the threads on the machine

Installing into Anaconda
------------------------

We've setup an user channel on Anaconda so that you can install PyPWA
into your Anaconda installation with the following command

$ conda install -c markjonestx pypwa


Notes for Apple Users
---------------------

With testing, we've found that PyPWA's environment in Anaconda doesn't
work well with Xterm in Mac OS X, however, Terminal found in your
Utilities folder does not seem to have the same issues.


Using from GitHub
-----------------
Expand Down
1 change: 0 additions & 1 deletion docs/doc_env.yml
Original file line number Diff line number Diff line change
Expand Up @@ -7,4 +7,3 @@ dependencies:
- recommonmark
- sphinx-autodoc-typehints
- sphinxcontrib-bibtex

49 changes: 0 additions & 49 deletions docs/source/developer_guide/environments/conda.rst

This file was deleted.

28 changes: 0 additions & 28 deletions docs/source/developer_guide/environments/index.rst

This file was deleted.

Loading

0 comments on commit 008438b

Please sign in to comment.