Documentation

• 1: Overview
• 2: ESA's 7th Earth Explorer Mission - BIOMASS
• 2.1: The BIOMASS mission
• 2.2: Measuring Forests
• 2.3: Facts & Figures
• 3: Science and Products
• 3.1: Forest Disturbance
• 3.2: Forest Height
• 3.3: AGB
• 4: Publications
• 5: Ecosystem
• 6: Contributing
• 6.1: Code of Conduct
• 6.1.1: Code of Conduct
• 6.1.2: Enforcement Manual
• 6.1.3: FAQ
• 6.1.4: Reporting Guide
• 6.2: Git Tutorial
• 6.2.1: Git installation
• 6.2.2: Collaborating on an existing project
• 7: Technical documentation

1 - Overview

What is BioPAL

The BIOMASS Product Algorithm Laboratory (BioPAL) is an evolution of the software developed for the BIOMASS prototype processor into an open source library to be used and contributed by the scientific community.

BioPAL GitHub repository collects the software routines for processing Level 1 SAR products to generate Level 2 forest products of Above Ground Biomass (AGB), Forest Heigth (FH) and Forest Disturbance (FD). More details about these products and BIOMASS can be found in Science and Products and BIOMASS.

Purpose

The BIOMASS Product Algorithm Laboratory (BioPAL) is an open-source scientific computing project, supporting the development of ESA’s BIOMASS mission algorithms coded in Python. The goal of the BioPAL project is to bridge the gap between advancements in scientific algorithm development and fast integration of these advancements into ESA’s BIOMASS’s ground operations. It is the first time that an official ESA Earth Explorer operational processor is supported by open and collaborative development of processing algorithms within the scope of an open-source software project and community.

First steps

• Getting Started: Get started with BioPAL !
• Tutorials: Check out some example use-case !

2 - ESA's 7th Earth Explorer Mission - BIOMASS

2.1 - The BIOMASS mission

ESA’s forest mission, BIOMASS is the first satellite to carry a P-band Synthetic Aperture Radar (SAR), in combination with polarimetric and interferometric capabilities. With an exceptionally large antenna of about 12 m diameter, BIOMASS generates a wavelength 70 cm long. Its radar signal will penetrate through the whole forest layer, seeing the larger elements of the tree (like trunk and branches, constituting a significant amount of biomass) and transparent to canopy leaves. The signal scattered back will therefore carry information about the forest structure that can be used to infer parameters such as forest biomass and forest height. Additionally, the mission will have a specific experimental tomographic phase to provide 3D views of forests.

Forests, especially in the tropics, represent a major sink of carbon dioxide. However, the spatial distribution of forest carbon stocks and related fluxes is not yet well-quantified. Above-ground biomass (AGB) in forests, which contains about 50% of carbon, is a central factor in the carbon budget, but in many parts of the planet AGB is poorly quantified due to the difficulty in collecting sufficient field measurements. Moreover, forest degradation and deforestation are causing release of the stored carbon back into the atmosphere, with negative impact on the ecosystem. Information from the BIOMASS mission will hopefully lead to a better understanding of the state of Earth’s forests, how they are changing over time, which quantitative role they play in the carbon cycle.

2.2 - Measuring Forests

Measuring the biomass of a tree is not an easy task: unless it is cut and then weighted, its mass can only be inferred indirectly from measurements. In classical forestry, this problem can be solved for instance by measuring the height, diameter of the trunk, wood density and then calculating the mass through allometry. However, in-situ measurements are usually costly and difficult to do in remote areas and thus limited in time and space.

Thanks to the long wavelength of P-band, BIOMASS signal, depending on polarisation, will penetrate through the whole forest layer and scatter back from the bone of the tree (trunk, branches). In this way, information about forest structure can be inferred from space on a global scale.

Compared to previous spaceborne SARs, BIOMASS is the first to offer polarimetry (PolSAR), polarimetric-interferometry (PolInSAR) and tomography (TomoSAR) altogether. Interferometric observations allow for the cancellation of the ground contribution from the signal, giving measurements more correlated to the volume of biomass in the tree. The combination of interferometry and polarimetry is used for the retrieval of forest height, while tomography allows mapping forests in 3D.

In addition, the BIOMASS mission will offer the opportunity to pursue secondary objectives such as the retrieval of sub-canopy Digital Terrain Model (DTM), mapping subsurface geology (theoretically possible in deserts and glaciers), measuring ice-sheets velocity and ionosphere properties.

Illustration of BIOMASS observation modes.

2.3 - Facts & Figures

Source:ESA

Launch: 2023

Launcher: Vega from Europe’s Spaceport in French Guiana

Satellite: Three-axis stabilised platform, 10 m high, 12 m wide and 20 m long (including large antenna)

Mass: 1170 kg (including 67 kg fuel)

Instrument: Fully polarimetric P-band Synthetic Aperture Radar (SAR) instrument operating at 435 MHz frequency

Power: 1.5 kW deployable solar array with 6.8 m2 triple junction GaAs cells; 144 Ah Li-ion battery

Orbit: Sun-synchronous, at altitude of 666 km inclined at 98 degrees, 3-day repeat cycle

Life: Minimum of 5.5 years

Communication: Science data transmitted to Kiruna (Sweden) via X-band downlink. Tracking, telemetry and command transmitted via S-band uplink and downlink

Mission control: ESA’s European Space Operations Centre (ESOC) in Darmstadt (Germany)

Data processing: ESA’s Centre for Earth Observation (ESRIN), in Frascati (Italy)

Scientific objectives: Deliver the first global and systematic measurements of forest height and biomass

Project and commissioning: Managed at ESA’s European Space Research and Technology Centre (ESTEC) in Noordwijk (the Netherlands)

Prime contractor: Airbus Defence and Space (UK)

3 - Science and Products

This section briefly illustrates the algorithms for the generation of BIOMASS products and implemented in BioPAL. For further information refer to the original source doi.org/10.3390/rs12060985. For specific topics see Publications.

The following table reports current target figures for the products.

Level 2 Product	Resolution	Accuracy
AGB	200 m	<20% (or 10 t/ha for AGB<50 t/ha)
FH	200 m	<30% for trees higher than 10 m
FD	50 m	detection at a specified level of significance

The products are intended to be global, covering forested land areas between 75°N and 56°S but subject to United States Department of Defense Space Object Tracking Radar (SOTR) restrictions, as illustrated.

Map of coverage of ESA and NASA satellite measurements of forest structure and biomass. The background shows the global coverage area of the NISAR mission and the sensitivity of NISAR to aboveground biomass values < 100 Mg/ha (green and yellow). The BIOMASS mission coverage includes the tropical belt and a portion of the northeast Siberia and the GEDI LiDAR sampling coverage from the International Space Station (ISS) between ±50 degrees latitude. Original source Forest Observation System.

3.1 - Forest Disturbance

Forest Disturbance (FD) is defined as an area where an intact patch of forest has been cleared, expressed as a binary classification of intact versus deforested or logged areas.

The disturbance product generation is based on Level 1 products: the restriction to severe disturbance allows the spatial resolution to be much finer than the other products since the associated changes in backscatter are expected to be several dBs in each intensity channel. The detection of changes in the polarimetric time series is based on hypothesis testing, where the null hypothesis is that in a time series of polarimetric data no change has occurred (at a given position and up to a given time). If this hypothesis fails at a given level of significance, then we assume a change has occurred. Note that it is closely related to the constant false alarm rate approach to target detection, in which the probability that an undisturbed pixel is incorrectly classified as disturbed is fixed. The estimates are updated each time a new acquisition is added to the stack, and significance levels can be attached to the test statistics.

An open issue in generating the BIOMASS disturbance product in this way is that changes in the signal caused by disturbance occur against a general background of non-forest and environmental changes. Further work is required to quantify how much these nuisance changes will increase the false detection rate. An important requirement is also to have an initial forest mask, derived from the BIOMASS data themselves or from some other source, in order to mask out detections in the non-forest areas.

3.2 - Forest Height

Forest Height (FH) is defined as upper canopy height according to the H100 standard used in forestry expressed in meters. H100 is defined as the average height of the 100 tallest trees/hectares.

The baseline methodology for BIOMASS interferometric phase is implemented by means of PolInSAR. Polarimetric-interferometric correlations estimated from data are linked to forest structural parameters such as forest height, ground-to-volume ratio, canopy extinction and temporal decorrelation through the Random Volume over Ground (RVoG) model. This model assumes that forest scattering comes from an extended layer of height equal to the canopy height above an opaque ground layer. The vertical distribution of scatterers is weighted by an extinction function, accounting for electromagnetic attenuation through the vegetation. The propagation through the volume is assumed to be independent of polarization.

The main challenges for BIOMASS are the presence of ground scattering in all polarizations due to the limited extinction at P-band, the limited resolution available at 6 MHz and temporal decorrelation due to the three-day repeat cycle. During the tomographic phase, FH will be estimated from the upper envelope of the tomographic voxel intensity, as well as the Digital Terrain Model (DTM) from the lower envelope to be ingested to the RVoG model as a-priori.

3.3 - AGB

AGB stands for Above Ground Biomass and is defined as dry weight of woody matter per unit area, expressed in t/ha = Mg/ha. AGB includes the mass of live organic matter above the soil including stem, stump, branches, bark, seeds and foliage, it does not include dead mass, litter and below-ground biomass.

The relationship between P-band SAR backscatter intensity of forests and forest AGB is governed by a large number of factors related to both forest characteristics (3D structure, species, growth stage, leaf and wood water content, etc.) and the environment (topography, soil moisture and surface roughness). AGB retrieval accounting for all these factors is ill-posed. This often led in the past to the formulation of very complex models and/or using a lot of reference data, which are usually not available on a global scale.

Level 2 Studies brought a new conceptual design of the retrieval, making full use of the BIOMASS interferometric observation capabilities to circumvent these limitations. This revision is based on three research results of the mission preparatory activities:

• the observational and modeling evidence that 30–40% of the total AGB in a dense tropical forest (BIOMASS main target area) is contained in the canopy region 25–35 m above the ground, and that the biomass in this region is highly correlated with the total AGB;
• the development of signal processing techniques (i.e., ground cancellation) to cancel out the backscatter signal from the ground layer using interferometric stacks of P-band data and Digital Terrain Model (DTM) to isolate the volume scattering element of the forest canopy;
• the development of an optimization approach to solve the model that minimizes the need for reference data.

All these results translate in the CASINO algorithm (CAnopy backscatter estimation, Subsampling, and Inhibited Nonlinear Optimisation). The algorithm inverts a power-law function relating AGB to ground cancelled backscatter data, through non-linear iterative minimization. Dimensionality of the problem is reduced by constraining the parameters according to phyisical considerations. The need for reference calibration data is minimized, though reference data still play a crucial role for absolute retrieval.

4 - Publications

You can find here a list of scientific publications related to BioPAL project:

Banda, F.; Giudici, D.; Le Toan, T.; Mariotti d’Alessandro, M.; Papathanassiou, K.; Quegan, S.; Riembauer, G.; Scipal, K.; Soja, M.; Tebaldini, S.; Ulander, L.; Villard, L. “The BIOMASS Level 2 Prototype Processor: Design and Experimental Results of Above-Ground Biomass Estimation” Remote Sensing, 2020, 12, 985. doi.org/10.3390/rs12060985

Soja, M.; Quegan, S.; Mariotti d’Alessandro, M.; Banda, F.; Scipal K.; Tebaldini, S.; Ulander, L. “Mapping above-ground biomass in tropical forests with ground-cancelled P-band SAR and limited reference data” Remote Sensing of Environment, Volume 253, 2021, 112153, ISSN 0034-4257. doi.org/10.1016/j.rse.2020.112153

Mariotti d’Alessandro, M.; Tebaldini, S.; Quegan, S.; Soja, M.; Ulander, L.; Scipal, K. “Interferometric Ground Cancellation for Above Ground Biomass Estimation” IEEE Transactions on Geoscience and Remote Sensing, vol. 58, no. 9, pp. 6410-6419, Sept. 2020. doi: 10.1109/TGRS.2020.2976854, download pdf

Banda, F.; Mariotti d’Alessandro, M.; Tebaldini, S. “Ground and Volume Decomposition as a Proxy for AGB from P-Band SAR Data” Remote Sensing 2020, 12, 240. doi.org/10.3390/rs12020240

Mariotti D’Alessandro, M.; Tebaldini, S. “Digital Terrain Model Retrieval in Tropical Forests Through P-Band SAR Tomography” IEEE Transactions on Geoscience and Remote Sensing, vol. 57, no. 9, pp. 6774-6781, Sept. 2019. doi: 10.1109/TGRS.2019.2908517

Alonso-González, A.; López-Martínez, C.; Papathanassiou, K.; Hajnsek, I. “Polarimetric SAR Time Series Change Analysis Over Agricultural Areas” IEEE Transactions on Geoscience and Remote Sensing, vol. 58, no. 10, pp. 7317-7330, Oct. 2020. doi: 10.1109/TGRS.2020.2981929

5 - Ecosystem

ESA-NASA MAAP

Link to ESA Link to NASA

The Multi-Mission Algorithm and Analysis Platform (MAAP) brings together data, algorithms, and computing in a common cloud environment to address the challenges related to ESA and NASA missions.

Forest Observation System

Link to FOS

The Forest Observation System is an international cooperation to establish a global in-situ forest biomass database to support earth observation and to encourage investment in relevant field-based observations and science.

NASA NISAR

Link to NASA

A dedicated U.S. and Indian InSAR mission, in partnership with ISRO, optimized for studying hazards and global environmental change.

NASA GEDI

Link to NASA

Global Ecosystem Dynamics Investigation (GEDI) is high resolution laser ranging of Earth’s forests and topography from the International Space Station (ISS).

6 - Contributing

The main goal of BioPAL is to advance the BIOMASS core processing algorithms for Forest Height estimation, Forest Disturbance assessment, or Above Ground Biomass estimation. We are always on the lookout for advances in estimating these metrics. If you have a novel integration of such an algorithm feel free to create an issue, a pull request or reach out to us via the slack channel.

However, open-source is about much more than contributing with new algorithms, we need your help in many ways:

• Submit a bug report or feature request on GitHub issues.
• Contribute an Jupyter notebook to our examples gallery.
• Assist us with user testing.
• Add to the documentation or help with our website, biopal.org
• Write unit or integration tests for our project.
• Answer questions on our GitHub issues, the MAAP forums, Slack channels, Stack Overflow, and Twitter.
• Translate our documentation into another language.
• Write a blog post, tweet, or share our project with others.
• Teach someone how to use BioPAL

Starting to Contribute

Whether you are a first time contributor to open-source or a seasoned open-source veteran interested in joining the BioPAL community, this section will guide you in:

• getting familiar with teh BioPAL Code of Conduct
• setting up and working with git
• setting up a BioPAL working environment
• and getting to know the standards to use when submitting a contribution to BioPAL

6.1 - Code of Conduct

6.1.1 - Code of Conduct

BioPAL is an engaged and respectful community made up of people from all over the world. Your involvement helps us to further our mission and to create an open platform that serves a broad range of communities, from research and education, to industry and beyond.

Naturally, this implies diversity of ideas and perspectives on often complex problems. Disagreement and healthy discussion of conflicting viewpoints is welcome: the best solutions to hard problems rarely come from a single angle. But disagreement is not an excuse for aggression: humans tend to take disagreement personally and easily drift into behavior that ultimately degrades a community. This is particularly acute with online communication across language and cultural gaps, where many cues of human behavior are unavailable. We are outlining here a set of principles and processes to support a healthy community in the face of these challenges.

Fundamentally, we are committed to fostering a productive, harassment-free environment for everyone. Rather than considering this code an exhaustive list of things that you cannot do, take it in the spirit it is intended - a guide to make it easier to enrich all of us and the communities in which we participate.

Importantly: as a member of our community, you are also a steward of these values. Not all problems need to be resolved via formal processes, and often a quick, friendly but clear word on an online forum or in person can help resolve a misunderstanding and de-escalate.

However, sometimes these informal processes may be inadequate: they fail to work, there is urgency or risk to someone, nobody is intervening publicly and you don’t feel comfortable speaking in public, etc. For these or other reasons, structured follow-up may be necessary and here we provide the means for that: we welcome reports by emailing biopal@esa.int. For more details please see our Reporting Guidelines.

This code applies equally to founders, developers, mentors and new community members, in all spaces managed by BioPAL. This includes our GitHub organizations, our chat rooms, in-person events and any other forums created by the project team. In addition, violations of this code outside these spaces may affect a person’s ability to participate within them.

Expected behavior

By embracing the following principles, guidelines and actions to follow or avoid, you will help us make BioPAL a welcoming and productive community. Feel free to contact the Code of Conduct Committee at biopal@esa.int with any questions.

1. Be friendly and patient.

2. Be welcoming. We strive to be a community that welcomes and supports people of all backgrounds and identities. This includes, but is not limited to, members of any race, ethnicity, culture, national origin, color, immigration status, social and economic class, educational level, sex, sexual orientation, gender identity and expression, age, physical appearance, family status, technological or professional choices, academic discipline, religion, mental ability, and physical ability.

3. Be considerate. Your work will be used by other people, and you in turn will depend on the work of others. Any decision you take will affect users and colleagues, and you should take those consequences into account when making decisions. Remember that we’re a world-wide community. You may be communicating with someone with a different primary language or cultural background.

4. Be respectful. Not all of us will agree all the time, but disagreement is no excuse for poor behavior or poor manners. We might all experience some frustration now and then, but we cannot allow that frustration to turn into a personal attack. It is important to remember that a community where people feel uncomfortable or threatened is not a productive one.

5. Be careful in the words that you choose. Be kind to others. Do not insult or put down other community members. Harassment and other exclusionary behavior are not acceptable. This includes, but is not limited to:

   • Violent threats or violent language directed against another person
   • Discriminatory jokes and language
   • Posting sexually explicit or violent material
   • Posting (or threatening to post) other people’s personally identifying information (“doxing”)
   • Personal insults, especially those using racist or sexist terms
   • Unwelcome sexual attention
   • Advocating for, or encouraging, any of the above behavior
   • Repeated harassment of others. In general, if someone asks you to stop, then stop

6. Moderate your expectations. Please respect that community members choose how they spend their time in the project. A thoughtful question about your expectations is preferable to demands for another person’s time.

7. When we disagree, try to understand why. Disagreements, both social and technical, happen all the time and BioPAL is no exception. Try to understand where others are coming from, as seeing a question from their viewpoint may help find a new path forward. And do not forget that it is human to err: blaming each other does not get us anywhere, while we can learn from mistakes to find better solutions.

8. A simple apology can go a long way. It can often de-escalate a situation, and telling someone that you are sorry is an act of empathy that does not automatically imply an admission of guilt.

Responding to inappropriate behavior

In some cases, individuals may violate the CoC in online or in-person situations. If any community member deems the action to be harmful to the community, they may act immediately to defuse the situation. This includes actions directed at the situation, rather than at an individual, such as locking a thread, temporarily suspending a user’s account in the community forum, calling a meeting break, or generally acting to de-escalate the situation. Follow-up your actions by reporting the incident to the CoC committee.

If the incident involves physical danger, or involves a threat to anyone’s safety (such as threats of violence), any member of the community may – and should – act unilaterally to protect the safety of any community member. This can include contacting law enforcement, other members of the Jupyter community, or other local personnel that are present.

In situations where an individual community member acts unilaterally, they must inform the Code of Conduct committee as soon as possible, by e-mailing biopal@esa.int within 24 hours.

Reporting

If you believe someone is violating the code of conduct, please report this in a timely manner. Code of conduct violations reduce the value of the community for everyone and we take them seriously.

You can file a report by emailing biopal@esa.int. For more details or information on reporting in-person at an event, please see our Reporting Guidelines.

Enforcement

For information on enforcement, please view the Enforcement Manual.

Document History

TBD

Acknowledgments

Original text courtesy of the Speak Up!, Django and Jupyter Projects, modified by BioPAL. We are grateful to those projects for contributing these materials under open licensing terms for us to easily reuse.

License

All content on this page is licensed under a Creative Commons Attribution license.

6.1.2 - Enforcement Manual

This is the enforcement manual followed by BioPAL’s Code of Conduct Committee. It’s used when we respond to an incident to make sure we are consistent and fair.

The Code of Conduct Committee

All responses to reports of conduct violations will be managed by a Code of Conduct Committee (“the committee”). The BioPAL Steering Council is responsible for vetting and appointing the Code of Conduct Committee. During periods where a separate Code of Conduct Committee is not appointed or is not available to handle a code of conduct report promptly, the BioPAL Steering Council will serve as the interim Code of Conduct Committee.

If a Code of Conduct report involves a member of the Steering Council or Code of Conduct Committee, that member will not participate in the investigation or any decisions related to that report.

Current Code of Conduct Committee members

Alphabetical by surname name:

• Clement Albinet, @ClementAlbinet (2020)
• Stefanie Lumnitz, @slumnitz (2020)
• Paolo Mazzucchelli, @pmazzucchelli (2020)

Enforcement guidelines and principles

Enforcing the Code of Conduct impacts our community today and for the future. It’s an action that we do not take lightly. When reviewing enforcement measures, the Code of Conduct Committee will keep the following values and guidelines in mind:

• Act in a personal manner rather than impersonal. The Committee can engage the parties to understand the situation, while respecting the privacy and any necessary confidentiality of reporters. However, sometimes it is necessary to communicate with one or more individuals directly: the Committee’s goal is to improve the health of our community rather than only produce a formal decision.

• Emphasize empathy for individuals rather than judging behavior, avoiding binary labels of “good” and “bad/evil”. Overt, clear-cut aggression and harassment exists and will be addressed unambiguously. But many scenarios that can prove challenging to resolve are those where normal disagreements devolve into inappropriate behavior from multiple parties. Understanding the full context and finding a path that re-engages all is hard, but ultimately the most productive for our community.

• Help increase engagement in good discussion practice: try to identify where discussion may have broken down and provide actionable information, pointers and resources that can help enact positive change on these points.

• Be mindful of the needs of new members: provide them with explicit support and consideration, with the aim of increasing participation from underrepresented groups in particular.

• Individuals come from different cultural backgrounds and native languages. While lack of intent to harm is not an excuse, try to identify any honest misunderstandings caused by a non-native speaker and help them understand the issue and how to change. Complex discussion in a foreign language can be very intimidating, and we want to grow our diversity also across nationalities and cultures.

• Our actions will reflect compassion for all individuals. We will seek to understand, to educate, and, as necessary, take action.

Mediation: voluntary, informal mediation is a tool at our disposal. In contexts such as when two or more parties have all escalated to the point of inappropriate behavior, it may be useful to facilitate a mediation process. This is only an example: the Committee can consider mediation in any case, mindful that the process is meant to be strictly voluntary and no party can be pressured to participate. If the Committee suggests mediation, it should:

• Find a candidate who can serve as a mediator.
• Obtain the agreement of the reporter(s). The reporter(s) have complete freedom to decline the mediation idea, or to propose an alternate mediator.
• Obtain the agreement of the reported person(s).
• Settle on the mediator: while parties can propose a different mediator than the suggested candidate, only if common agreement is reached on all terms can the process move forward.
• Establish a timeline for mediation to complete, ideally within two weeks.

The mediator will engage with all the parties and seek a resolution that is satisfactory to all. Upon completion, the mediator will provide a report (vetted by all parties to the process) to the Committee, with recommendations on further steps. The Committee will then evaluate these results (whether satisfactory resolution was achieved or not) and decide on any additional action deemed necessary.

How the committee will respond to reports

When a report is sent to the committee they will immediately reply to the reporter to confirm receipt. This reply must be sent within 48 hours, and the group should strive to respond much quicker than that.

See the Reporting Guidelines for details of what reports should contain. If a report doesn’t contain enough information, the committee will obtain all relevant data before acting. The committee is empowered to act on the Steering Council’s behalf in contacting any individuals involved to get a more complete account of events.

The committee will then review the incident and determine, to the best of their ability:

• What happened.
• Whether this event constitutes a Code of Conduct violation.
• Who are the responsible party(ies).
• Whether this is an ongoing situation, and there is a threat to anyone’s physical safety.

This information will be collected in writing, and whenever possible the group’s deliberations will be recorded and retained (i.e. chat transcripts, email discussions, recorded conference calls, summaries of voice conversations, etc).

It is important to retain an archive of all activities of this committee to ensure consistency in behavior and provide institutional memory for the project. To assist in this, the default channel of discussion for this committee will be the BioPAL e-mail list accessible to current and future members of the committee as well as members of the Steering Council upon justified request. If the Committee finds the need to use off-list communications (e.g. phone calls for early/rapid response), it should in all cases summarize these back to the list so there’s a good record of the process.

The Code of Conduct Committee should aim to have a resolution agreed upon within one week. In the event that a resolution can’t be determined in that time, the committee will respond to the reporter(s) with an update and projected timeline for resolution.

Incident Response and Committee Actions

If the act is ongoing, or involves a threat to anyone’s safety (e.g. threats of violence), any committee member may act immediately (before reaching consensus) to address the situation. In ongoing situations, any member may decide to employ any of the tools available to the committee, including bans and blocks.

If the incident involves physical danger, any member of the committee may – and should – act unilaterally to protect the safety of those involved. This can include contacting law enforcement (or other local personnel) and speaking on behalf of the BioPAL Steering Council.

In situations where an individual committee member acts unilaterally, they must report their actions to the committee for review within 24 hours.

At events where no Committee members may be present, an event organizer will act as their delegate. They will forward any reports to the Committee, as well as a summary of any action they may have taken during the event.

Resolutions

The committee must agree on a resolution by consensus. If the group cannot reach consensus and deadlocks for over two weeks, the group will turn the matter over to the Steering Council for resolution.

Possible responses may include:

• Taking no further action
  • if we determine no violations have occurred.
  • if the matter has been resolved publicly while the committee was considering responses.
• Coordinating voluntary mediation: if all involved parties agree, the Committee may facilitate a mediation process as detailed above.
• Remind publicly, and point out that some behavior/actions/language have been judged inappropriate and why in the current context, or can but hurtful to some people, requesting the community to self-adjust.
• A private reprimand from the committee to the individual(s) involved. In this case, the group chair will deliver that reprimand to the individual(s) over email, cc’ing everyone involved.
• A public reprimand. In this case, the committee chair will deliver that reprimand in the same venue that the violation occurred, within the limits of practicality. E.g., the original issue report for a CoC violation within a filed issue, but for a chat room discussion where the person/context may be gone, they can be reached by other means. The group may choose to publish this message elsewhere for documentation purposes.
• A request for a public or private apology, assuming the reporter agrees to this idea: they may at their discretion refuse further contact with the violator. The chair will deliver this request. The committee may, if it chooses, attach “strings” to this request: for example, the group may ask a violator to apologize in order to retain one’s membership on a mailing list.
• A “mutually agreed upon hiatus” where the committee asks the individual to temporarily refrain from community participation. If the individual chooses not to take a temporary break voluntarily, the committee may issue a “mandatory cooling off period”.
• A permanent or temporary ban from some or all BioPAL spaces (BioPAL organisation, Slack, etc.). The group will maintain records of all such bans so that they may be reviewed in the future or otherwise maintained.

Once a resolution is agreed upon, but before it is enacted, the committee will contact the original reporter and any other affected parties and explain the proposed resolution. The committee will ask if this resolution is acceptable, and must note feedback for the record. However, the committee is not required to act on this feedback.

Finally, the committee will make a report to the BioPAL Steering Council (as well as the BioPAL core team in the event of an ongoing resolution, such as a ban).

The committee will never publicly discuss the issue; all public statements will be made by the chair of the Code of Conduct Committee or the BioPAL Steering Council.

Conflicts of Interest

In the event of any conflict of interest, a committee member must immediately notify the other members, and recuse themselves if necessary.

Acknowledgments

Original text courtesy of the Speak Up!, Django and Jupyter Projects, modified by BioPAL. We are grateful to those projects for contributing these materials under open licensing terms for us to easily reuse.

License

All content on this page is licensed under a Creative Commons Attribution license.

6.1.3 - FAQ

This FAQ attempts to address common questions and concerns around the BioPAL community’s Code of Conduct. If you still have questions after reading it, please feel free to contact us at biopal@esa.int.

Why have you adopted a Code of Conduct?

We think the BioPAL community is awesome. If you’re familiar with the BioPAL community, you’ll probably notice that the Code basically matches what we already do. Think of this as documentation: we’re taking implicit expectations about behavior and making them explicit.

Maintaining a Code of Conduct forces us to consider and articulate what kind of community we want to be, and serves as a constant reminder to put our best foot forward. But most importantly, it serves as a signpost to people looking to join our community that we feel these values are important.

We know that the BioPAL community is open, friendly, and welcoming. We want to make sure everyone else knows it too.

What does it mean to “adopt” a Code of Conduct?

For the most part, we do not think it means large changes. We think that the text does a really good job describing the way the BioPAL community already conducts itself. We expect that most people will simply continue to behave as they have in the past.

However, we do expect that people will abide by the spirit and words of the Code of Conduct when in “official” BioPAL spaces. In practice, BioPAL spaces include mailing lists, various communication channels, and events.

What happens if someone violates the Code of Conduct?

We are all stewards of our community, and are encouraged to participate in ways that defend the values highlighted in this document and help others understand when their actions go against these values (by engaging them and directing them to this document if necessary). If that doesn’t work, or if you need more help, you can contact biopal@esa.int. For more details please see our Reporting Guidelines.

Acknowledgments

Original text courtesy of the Speak Up!, Django and Jupyter Projects, modified by BioPAL. We are grateful to those projects for contributing these materials under open licensing terms for us to easily reuse.

License

All content on this page is licensed under a Creative Commons Attribution license.

6.1.4 - Reporting Guide

If you choose to email, please include the following information:

• Your contact info (not required)
• Names (real, nicknames, or pseudonyms) of any individuals involved. If there were other witnesses besides you, try to include them as well (not required)
• When and where the incident occurred. Please be as specific as possible.
• Your account of what occurred. If there is a publicly available record (e.g. a Slack chat or GitHub issue) please include a link
• Any extra context you believe exists for the incident
• If you believe this incident is ongoing
• Any other information you believe we should have

Note: with anonymous reports, there are inherent limits in our ability to do follow-up or collect additional information. Hence we suggest that if you would like to remain anonymous, you at least create a throw-away email address without your real name.

What happens after you file a report?

You will receive an email from the BioPAL Code of Conduct Committee acknowledging receipt immediately. We promise to acknowledge receipt within 48 hours (and will aim for much quicker than that).

The committee will immediately communicate to review the incident and determine:

• What happened
• Whether this event constitutes a Code of Conduct violation
• Who the individual(s) involved were
• Whether this is an ongoing situation, or if there is a threat to anyone’s physical safety

If this is determined to be an ongoing incident or a threat to physical safety, the committee’s immediate priority will be to protect everyone involved. This means we may delay an “official” response until we believe that the situation has ended and that everyone is physically safe.

The Code of Conduct committee will then follow the standard procedure to arrive at and communicate a resolution.

Appealing the Code of Conduct Committee’s Response

To appeal a decision of the Code of Conduct Committee, contact the BioPAL Steering Council at biopal@esa.int with your appeal and they will review the case.

The Steering Council will gather all relevant information from the Committee and provide a resolution within two weeks. If more time is required, it should inform the appellant within that time frame.

Acknowledgments

Original text courtesy of the Speak Up!, Django and Jupyter Projects, modified by BioPAL. We are grateful to those projects for contributing these materials under open licensing terms for us to easily reuse.

License

All content on this page is licensed under a Creative Commons Attribution license.

6.2 - Git Tutorial

6.2.1 - Git installation

Before you start using git for your Python projects or other collaborative purposes, you have to choose and set up an environment that allows you to work with git and install the latest version of git.

Git can be used through many different interfaces. Throughout this collection of resources we will predominantly be working with git in the command line in order to manage collaborative projects. To get started you’ll set up a command line interface, install git and optionally a gui. Gui’s are often helpful to check a projects branch structure and see which branches are merged, not merged and under development.

Linux

Checklist:

• git & git bash installed
• configured identity
• git command line interface personalized (optional)
• set-up user account on i.e. github or gitlab

If you want to install the basic Git tools on Linux via a binary installer, you can generally do so through the package management tool that comes with your distribution. If you’re on Fedora (or any closely-related RPM-based distribution, such as RHEL or CentOS), you can use dnf:

sudo dnf install git-all

If you’re on a Debian-based distribution, such as Ubuntu, try apt:

sudo apt install git-all

For more options, there are instructions for installing on several different Unix distributions on the Git website, at linux installation page.

Windows

Checklist:

• install VS Code editor (optional)
• git & git bash installed
• configured identity
• git gui installed (optional)
• git command line interface personalized (optional)
• set-up user account on i.e. github or gitlab

Editor: Visual Studio Code

If you are not familiar with vim, nano or other text editors used in the command line you can make access to git easier by installing the open-source text editor and Python IDE Visual Studio Code (VS Code). Download the windows version of VS Code, then run the installer. Accept most default configurations on all pages except for the following:

• (Optional) On the Select Additional Tasks page, check “Create a desktop icon” under “Additional icons”.
• Also on the Select Additional Tasks page check all four boxes under “Other”
  1. “Add ‘Open with Code’ action to Windows file context menu”
  2. “Add ‘Open with Code’ action to Windows directory context menu”
  3. “Register Code as an editor for supported file types”
  4. “Add to PATH” (this should be selected by default).

Git and Bash Shell

(Please note VS Code should be installed before this step.) There are multiple different ways to install git on Windows. I recommend installing the official and latest git version. It will come with a command line tool. Download the official windows installer form here, then run the installer. If you have not used git before, accept most default configurations on all pages except for the following:

• (Optional) On the Select Components page, check “On the Desktop” under “Additional icons”.
• On the Choosing the default editor used by Git page, think about which editor you’d prefer to use and feel comfortable using. “Use Visual Studio Code as Git’s default editor” from the drop-down menu if you are not comfortable yet using i.e. vim.

To check if your installation was successful open teh Git Bash program (if you checked the option you can find it as a new icon on your desktop). The type:

git --version

to check which version of git was installed. Then run the following commands, make sure you add your name and e-mail address, to let git know who you are:

git config --global user.name "Name Surname"

git config --global user.email "name.surname@examplemail.com"

MacOS

Checklist:

• commandline/ terminal available
• git installed
• configured identity
• git gui installed (optional)
• git command line interface personalized (optional)
• set-up user account on i.e. github or gitlab

Command line interface

Using the command line on MacOS is straight forward as MacOS comes with the Terminal already installed. The easiest way to open the Terminal is to search for it via MacOS Spotlight. Open spotlight by pressing cmd+space or navigating to the Search icon in the top right corner. Then look for the Terminal and double click to open.

Installing git

There are multiple ways to install git on MacOS and modern Macs ship with a pre installed version of git through the Xcode Command Line Tools. To check if git is installed type in your terminal:

git --version

If git is not already installed you’ll get prompted to install it. Follow the suggestions in the command line. Once the installation has finished, run the following commands, make sure you add your name and e-mail address, to let git know who you are:

git config --global user.name "Name Surname"

git config --global user.email "name.surname@examplemail.com"

Gui

In most cases, gitk, a gui to check your projects branch structure, will automatically be installed with git on MacOS. You can check if gitk is installed by typing:

gitk --all

A small separate pop-up window should open, either showing you the branch structure of the project - in case you opened gitk in a git directory -, or showing a message explaining that not git repository could be found.

There are many alternatives to gitk with more elaborative gui’s, i.e. gitdesktop. However, gitk provides all functionality needed for the beginning. of course there is also a way to check your branch structure directly from the terminal without a gui. You could for example inspect the output of:

git log --oneline

Trouble shooting

In case you have trouble accessing git via the commandline, try:

• Installing the latest version of Xcode through the app store
• Install git using Homebrew

Personalized command line interface

Personalizing your command line interface, for example, to show the branch name you are currently using, can make working with git much easier. Copy these following lines:

parse_git_branch() {
     git branch 2> /dev/null | sed -e '/^[^*]/d' -e 's/* \(.*\)/ (\1)/'
}
export PS1="\u@\h \[\033[32m\]\w\[\033[33m\]\$(parse_git_branch)\[\033[00m\] $ "

and past them to your ~/.bashrc file. Then restart your terminal, i.e. by typing source ~/.bashrc or opening and closing it.

Further reading and Sources:

• git
• resources to learn git

6.2.2 - Collaborating on an existing project

This section introduces you to getting started with BioPAL in git and gives you an example of a basic git workflow.

Setting-up, cloning an existing project

1. Navigate to the existing project on github in your web browser:

https://github.com/biopal/biopal

2. Create a fork of the project in your profile by clicking the fork icon in the top right corner and selecting you profile. This allows you to track your changes, and save them to your own profile before integrating them to the official version of the project.

3. Copy the link of your forked version of the project, found under the green code button on the right hand side:

https://github.com/YOURUSERNAME/biopal.git 

3. In the terminal, navigate to a directory you’d like to store your project in. You can for example create a new projects directory to store your git projects under. Type into git bash or terminal:

mkdir ~/projects # to create a directory
cd ~/projects    # to navigate to the directory

4. Clone the project using git clone <url>:

git clone https://github.com/biopal/biopal.git

This creates a new directory named ~/projects/biopal, initializes a .git directory inside it, pulls down all the data for that repository, and checks out a working copy of the latest version. If you go into the new biopal directory that was just created, you’ll see the project files in there, ready to be worked on or used.

5. Check your remotes by typing git remote -v into the command line. Your git remotes point to the online github repository and will help you synchronize with your online fork of the project. You will now set up your git remote, aiming for git remote -v to display:

origin	https://github.com/YOURUSERNAME/biopal.git (fetch)
origin	https://github.com/YOURUSERNAME/biopal.git (push)
upstream	https://github.com/biopal/biopal.git (fetch)
upstream	https://github.com/biopal/biopal.git (push)

It is likely that git remote -v will look more something like this:

upstream	https://github.com/YOURUSERNAME/biopal.git (fetch)
upstream	https://github.com/YOURUSERNAME/biopal.git (push)

We will first, need to rename upstream to origin which will point to your personal fork of the project created in step 2. Type:

git remote rename upstream origin

Check if upstream was renamed to origin typing git remote -v. Next we need to add a new upstream this will point to the original project you saw in step 1. To add an upstream type:

git remote add upstream https://github.com/biopal/biopal.git

Note depending on your access/ development rights in the origin project you may or may not be able to push to upstream. In general it is considered best practice to ALWAYS push to origin first, and then point a Pull Request to upstream if upstream is a collaborative project. To finish, verify that all changes were made successfully checking the output of git remote -v.

You are now ready to make your first changes!

Making changes in your project and adding them

General workflow:

1. Make sure you are on the right working branch or create a new branch: git checkout -b NEW
2. Make changes
3. Stage changed files for commit: git status (optional, to check changed files), git add <file_name>
4. Commit staged files and write a commit message: git commit -m "[ENH] my message"
5. Push commits in branch NEW to github origin: git push origin NEW
6. Create a PR pointing your branch NEW to your origin main or to the upstream main
7. Include changes in your local main branch: git checkout main, then git pull upstream or git pull origin
8. Repeat with step 1 or rebase your working branch NEW onto your local main and repeat with step 2: git checkout NEW and git rebase main NEW

Further Reading:

• Working with remotes
• Git basics
• Why branching

7 - Technical documentation

Link to readthedocs.