cjtu/plutopy

Learn to contribute to open source in under 20 minutes! Scroll down for more details 👇

Plutopy

Welcome to plutopy, a community that teaches and promotes open source planetary science!

The goal of this repository is to help scientists learn to use open source tools to improve the quality and reproducability of their research.

What is open source?

Broadly, open source describes anything publicly available that people can modify and share. There has been a recent surge in open practices being adopted in industry and academia and plutopy will help you leverage these practices for your own research. To read more about open source, see the links below:

• Why open source science?
• The open source way
• In practice: OSGEO's philosophy

Get started

Plutopy participation is open to everyone! To get acquainted with this repository and the basics of plutopy, you will need:

• A free Github account (sign up here)
• A computer with Git (try git --version in a terminal. No luck? See install guide here)
• About 20 minutes to complete the plutopy tutorial here

Not convinced?

Who can join plutopy?

Plutopy is open to anyone who is:

• interested in learning open source techniques for scientific research
• planning on sharing code with the wider community
• passionate about spreading open-source practices and making science more reproducible

What will I learn?

Currently, plutopy is focused on teaching the following skills:

• Git, GitHub and version control
• How to package research code to share with others
• Reproducible analysis with Jupyter notebooks

I already use open source practices in my research

Great! We are looking for experienced scientists who use open source tools on a day-to-day basis to help make plutopy more accessible to beginners and help us make open source practices the norm in academia.

I don't know anything about Pluto, planets and image data

That's ok! This repository is organized as a planetary image analysis package to serve as an example, but the open source tools taught here are broadly applicable to basic research in all academic disciplines.

How it works

Learning with Plutopy is entirely self-paced. You will start here with a basic introduction to Git, GitHub and the Plutopy repository. From there, you will be ready to start new tutorials, contribute your insights or improvements to the main repository, or use Plutopy as an example to open-source your own code. You receive feedback on your contributions as you progress in your learning. Over time, Plutopy will grow with member contributions to become a better resource for learning open-source science.

Applying skills to my own work

Plutopy is intended to be used as an example repository for academics interested in releasing an open-source code repository. All examples you find in plutopy are open-source (see our License) and can be edited or adapted for use in your own work, as long as plutopy is cited in any abstracts or publications that it supports (see citable DOI).

Joining and Contributing to Plutopy

Plutopy is made possible by its contributors. By completing the first tutorial, you will learn the basics of open-source collaboration by becoming a Plutopy contributor! If you already know the basics of Git and GitHub, but would like to contribute, you can first read CONTRIBUTING.md and then head over to the issue tracker to see what issues are open. All are welcome!

Code of Conduct

This repository is governed by a code of conduct. See CODE_OF_CONDUCT.md for more details.

License

This repository is released under the MIT license for open and warranty-free use and reproduction. See the LICENSE for more details. To learn more about the importance of an open-source license, see this explanation. To learn what the legal jargon in a particular license means, check out ChooseALicense.com.

plutopy's Issues

Add a function that takes a named feature and plots the area around it

This issue builds off of #2 and #3. You may want to wait until those are finished to take this one on.

Write a function in helpers.py that:

• Takes the name of a named feature from named_features.csv as an argument
• Gets the center lat, center lon, and diameter of that feature and converts these into a lat/lon extent
• Uses the min / max lat and lon to plot the area around that feature

Add an example in jupyter_notebooks/ (you can edit tutorial.ipynb or make your own notebook) which shows your function in action, plotting multiple named areas on Pluto

Add a function that reads named_features.csv into a pandas DataFrame

The pandas package excels at storing and manipulating tabular data. The file /data/named_features.csv is a table of named features on Pluto and some facts about them.

Write a function in helpers.py that:

• reads the named_features.csv into a pandas dataframe

Add an example in jupyter_notebooks/ (you can edit tutorial.ipynb or make your own notebook) which shows how to call this function and some cool manipulations you can do with pandas methods.

Fix typos!

Every time there is text, there are typos. If you find one (or more) anywhere in this repository, you can fix them!

Submit your copy-edits as a separate pull request from other work you are doing.

[Task 1]: Submitting your first pull request

Your First Open Source Contribution

These steps will walk you through making your first contribution to a public GitHub repository by adding your name to the Plutopy CONTRIBUTORS.md file. This tutorial is adapted from an excellent teaching repository, first-contributions.

First time using GitHub?

You will need to sign up for a free account here.

First time using Git?

This tutorial involves use of Git terminal commands. To check if you have Git on Mac/Linux, open a terminal and type git --version. If you need to install Git, you can learn how to do so here.

If this is your first time using Git, you will need to configure it so that your work is properly attributed to you. Make sure you use the same email that you used to sign up for GitHub.

git config --global user.name "Firstname Lastname"
git config --global user.email "[email protected]"

Fork this repository

Fork this repository by clicking on the fork button on the top of the main repository page here. You may want to open this in a new window to keep these instructions up!

Clicking fork will create a copy of this repository in your GitHub account.

Clone the repository

Now you need to clone your forked repository to your machine. Go to your GitHub account, open the forked repository, click on the clone or download button.

Next, copy the url you see (you should see your GitHub username in the url).

Open a terminal, navigate to where you want to clone the repository, and run the following git command:

git clone "url you just copied"

where "url you just copied" (without the quote marks) is the url to your fork of this project.

For example:

git clone https://github.com/this-is-you/plutopy.git

where this-is-you is your GitHub username.

This copies your forked Plutopy repository from the GitHub website to your machine!

Create a branch

Enter the repository directory on your computer (if you are not already there):

cd plutopy

Now create a branch using the git checkout command:

git checkout -b <new-branch-name-here>

The name of the branch should describe the change you are planning on making. For example:

git checkout -b add-christian-to-contributors

Make necessary changes and commit those changes

Now let's see what is in the directory that you just cloned/

ls

Notice the CONTRIBUTORS.md file? This is the file we want to add your name to.

Open CONTRIBUTORS.md file in any text editor on your computer (you can use a terminal text editor like emacs if you are familiar, but NotePad and TextEdit will work fine as well). With the file open, add your name to the middle of the list somewhere. Don't add it at the beginning or end of the file. Now, save the file and return to the terminal.

If you are in the plutopy project directory and execute the command git status, you'll see there are changes.

Add those changes to the branch you just created using the git add command:

git add CONTRIBUTORS.md

Run git status again and you will see that your changes are staged and ready to commit.

In Git, each change to a repository is locked in with a "commit" which also acts like a snapshot of the repository at a certain point in time. Now commit your change using the git commit command:

git commit -m "Add <your-name> to contributors list"

replacing <your-name> with your name. This message describes the change you made so that it can be easily found later.

Push changes to GitHub

Push your changes using the command git push:

git push origin <add-your-branch-name>

replacing <add-your-branch-name> with the name of the branch you created earlier. You will likely need to enter your GitHub username and password.

Submit your changes for review

If you go to your forked repository on GitHub, you'll see a Compare & pull request button. Click on that button.

This is where you would normally add a description of the changes in your pull request. You can reference an issue that you addressed by typing #num where num is the number of the issue. Your description could look something like this:

Finished issue #1 by adding <my-name> to the contributors list.

Now submit the pull request.

Review

The pull request is the most common way of making a contribution to an open-source repository. Once a plutopy maintainer sees your request, they will review your changes. If anything needs to be updated before your change is added to the main repository, they will comment on your request and let you know.

You will get a notification once the changes have been merged, at which point you should see your name in the main plutopy repository here!

Where to go from here?

Great job submitting your first open source contribution! You have now seen the common fork -> clone -> edit -> commit -> Pull request workflow used by most open source GitHub repos.

While your contribution is being reviewed, a good next step would be to join the plutopy Gitter, a chat where plutopy members can talk about issues and open science. Next, you can check out the plutopy contributing guidelines which have some next steps for continuing to learn with plutopy (see below).

Contributing guidelines

Many open source repositories will have contributing guidelines in a file called CONTRIBUTING.md. This file provides general info and guidelines to follow to get started contributing to a repository and to make sure your contributions meet the repository's standards. The contributing guidelines for this project can be found at CONTRIBUTING.md. Review them and follow the instructions to get a plutopy environment set up on your computer.

GitHub Issues

Issues can be opened by anyone to communicate bugs or feature requests to the maintainers of a GitHub repo. To contribute to an open source repository, you will generally find an issue you would like to work on, comment on the issue to let the maintainers know that you are working on it, and then do exactly as we did above (fork, clone, edit, commit) and submit your fix as a pull request. Once you have read the contributing guidelines, check out the issue board to find a new tutorial to work on.

Add documentation / docstrings

Have you come across a function lacking a """docstring"""? Did you find some part of the README or CONTRIBUTING instructions confusing or lacking? Feel free to update them!

Submit your changes as a pull request separate from any changes you make to the code.

Add a function that prettifies image plotting

Write a function in helpers.py that:

• uses the matplotlib.pyplot.imshow() function
• uses pyplot options to make the plot prettier in some way
• Any of the following could make the plot prettier, you can choose some or do all
  • Add a title
  • Add x and y labels
  • Choose a custom color palette (Kudos if it's colorblind compliant)
  • Display the x and y axes in lat / lon instead of pixels (requires a bit of math)

Add an example in jupyter_notebooks/ (you can edit tutorial.ipynb or make your own notebook) which shows how to call this function and the cool options you added.

[Start Here]: Newcomer check-in and FAQ

Welcome to Plutopy! 🎉

If you have a GitHub account, you can check in by saying hello, introducing yourself or asking a question below!

To get a GitHub account, you can join here. It's free!

FAQ

What is Plutopy? Plutopy is a community aimed at teaching and advocating for reproducible research in the planetary sciences.

What if I don't do Planetary Science? That's ok! If you are interested in learning about reproducible research, most of the skills taught here are transferable to other areas of science, data science, etc. The examples will revolve around planetary analysis of Pluto though!

Is Pluto a planet? Next question...

I have no experience with this stuff and it all seems daunting Don't worry! The modules here assume little to no experience with programming, Git, or planetary science! All it takes is an interest in learning about reproducible research and an internet connection.

I'm stuck, where do I go for help? The issue board is the best way to get in touch or find help. Chances are, if you got stuck because something was unclear or you don't know what to do next, someone else could have the same problem! You can check if there are any issues that are similar to your problem, and if not, open a new issue (instructions here). A Plutopy collaborator will respond as soon as possible.

I'm ready to start learning! Great! The first task is #1. You got this! 💪

Add a function that reads data from the image given lat / lon extents

Add a function to helpers.py that:

• takes minimum latitude, maximum latitude, minimum longitude, maximum longitude as arguments
• converts these values to image pixel values
• returns the specified section of the image as a NumPy array

Hint: the GDAL.Dataset.GetGeoTransform and GDAL.Dataset.ReadAsArray() functions may be useful.