pav3 3.0.0__tar.gz

pav3-3.0.0/CHANGELOG.md

@@ -0,0 +1,410 @@
+# Changelog
+
+<!--
+Style guide:
+https://common-changelog.org/
+-->
+
+<!-- TEMPLATE
+## [x.y.z] - YYYY-MM-DD
+
+### Changed
+- 
+
+### Added
+- 
+
+### Removed
+-
+
+### Fixed
+-
+
+-->
+
+## 3.0.0 - 2026-10-28
+
+_First stable release of PAV 3, listing changes since the last prerelease (3.0.0.dev26)._
+
+### Changed
+- **Breaking:** Low-confidence alignment filtering (`LCALIGN`) is off by default (config parameter `lc_model`
+  defaults to `none`). It removed correct calls in highly diverged regions such as HLA class II. Set `lc_model` to
+  `default` for the previous behavior.
+- **Breaking:** Alignment records with MAPQ below 20 are filtered by default (new config parameter `min_mapq`).
+  Their variants are filtered with `MAPQ`, and their regions are not callable. Low-MAPQ fragments in satellites and
+  repeats produced false calls that broke haplotype reconstruction from the VCF.
+- **Breaking:** Haplotype merge defaults (`pav3.const.DEFAULT_MERGE_PARAMS`) for `insdel` and `cpx` merge only
+  matching alleles: same position and end, size and sequence identity of at least 0.998 for insertions and
+  deletions, and 0.98 for complex variants (with segment overlap 0.8). The previous population-style tolerances
+  merged different alleles from the two haplotypes into one homozygous record and moved variants up to 200 bp to the
+  other haplotype's position. Override with the new `merge_params` config parameter.
+- **Breaking:** VCF records at the same position are combined into multi-allelic records when they have the same
+  filter and no haplotype carries more than one of them, so different alleles on two haplotypes are written as one
+  record (e.g. `1|2`) instead of two overlapping records (`1|0` and `0|1`).
+- **Breaking:** Complex variants are written as sequence-resolved REF and ALT alleles by default. The record
+  replaces the reference bases skipped by the variant with the variant sequence, so applying it to the reference
+  (e.g. `bcftools consensus`) reconstructs the haplotype. Set `vcf_cpx_symbolic` to write `<CPX>` alleles.
+- **Breaking:** VCF `INFO/SVLEN` is always positive. Deletions are no longer negated.
+- **Breaking:** VCF `INFO/SVLEN` is written only for symbolic ALT alleles. VCF defines it for symbolic structural
+  variant alleles and directs writers to use the missing value for all others, where REF and ALT give the length.
+  Multi-allelic records combining an SNV with an indel carried `SVLEN=.,N`, which crashed Truvari, and htslib 1.22
+  sized sequence-resolved records by SVLEN.
+- **Breaking:** VCF `INFO/END` and `INFO/SEQ` are written only for symbolic ALT alleles, where REF and ALT do not
+  carry the span or the sequence. `SEQ` is upper-cased to match REF and ALT, and is not written for derived
+  variants, where it does not describe the alternate allele.
+- **Breaking:** VCF INFO values no longer contain literal commas, which VCF reserves as the value delimiter. `DUP`
+  separates regions with `/`, and `CPX_REF_TRACE` and `CPX_QRY_TRACE` drop thousands separators. The `trace_ref`
+  and `trace_qry` variant table columns are unchanged.
+- **Breaking:** Tandem and inverted duplications are written as `<DUP:TANDEM>` and `<DUP:INVDUP>` rather than
+  `INFO/SUBTYPE`.
+- **Breaking:** Replaced VCF `INFO/HOMREF` and `INFO/HOMQRY` with the reserved `INFO/HOMLEN`, summing upstream and
+  downstream homology from reference breakpoints for `DEL` and `DUP` and query breakpoints for `INS` and `CPX`.
+- **Breaking:** Workflow targets are renamed for the output they build: `pav_all` to `vcf` (still the default),
+  `align_all` to `align`, `call_tables_all` to `call_tables`, `call_tables_hap_all` to `call_tables_hap`,
+  `tracks_all` to `tracks`, and `tracks_align_all` to `tracks_align`. The rules previously named `call_tables`,
+  `call_tables_callable`, and `tracks_align` are renamed `call_merge_haps`, `call_callable`, and
+  `tracks_align_trim`, so Snakemake profiles setting resources for them need the new names.
+- **Breaking:** The assembly table is the first of `assemblies.csv`, `assemblies.xlsx`, and `assemblies.tsv` found
+  in the run directory (previously `assemblies.tsv`, then `assemblies.xlsx`). A run directory with more than one of
+  these files may read a different table.
+- Tighter compliance with VCF 4.5.
+- Complex variant tables have new columns `seq_ref_pos` and `seq_ref_end`, the reference region the variant
+  sequence replaces.
+- VCF INFO headers declare an accurate `Number`. `END` is `Number=1` and `SVLEN` is `Number=A`, matching the
+  reserved keys; all others are `Number=A`. All were previously `Number=.`.
+- Contig names embedded in VCF INFO values (`QUERY`, `DUP`, and the complex variant traces) are percent-encoded
+  where they contain `;`, `=`, `,`, `%`, a tab, or a line break, as VCF requires.
+- VCF records are sorted in reference order, the order of the `##contig` header lines, rather than by chromosome
+  name (`chr1`, `chr10`, `chr2`). Tools validating records against the sequence dictionary (e.g. Picard) reject
+  other orders.
+- VCF REF and ALT reduce IUPAC ambiguity codes to the base that is first alphabetically (e.g. `R` to `A`), as VCF
+  requires.
+- The VCF header writes `##fileDate` instead of `##filedate`, and `##reference` as the reference file name instead
+  of a `file://` URI, which read the file name as a host name.
+- Variant tracks report `.` for strand. The strand column was never set, and a variant carries no orientation of
+  the reference feature it is drawn on.
+- The multi-allelic record summary is printed only with `verbose`, and its statistics are not computed otherwise.
+- `pav3 --help` directs users to `batch` and lists `call` as deprecated.
+- The README cites the PAV 3 preprint (https://doi.org/10.1101/2024.12.19.629504), is reorganized into install,
+  configuration, run, and output sections, and documents the workflow targets and the other `pav3` subcommands.
+
+### Added
+- YAML configuration file `pav.yaml` (or `pav.yml`), accepting the same parameters as `pav.json`. PAV reads
+  `pav.json` only if no YAML configuration is found, and warns and uses the YAML configuration if both are present.
+- Config parameters `min_mapq`, `merge_params`, and `vcf_cpx_symbolic`.
+- VCF `INFO/SVCLAIM` is written as `J` for symbolic `DEL` and `DUP` alleles, which VCF requires. PAV calls these
+  from non-reference adjacencies rather than from a measure of DNA abundance.
+- Duplications derived from insertions placing a copy of a reference region. A tandem-duplication insertion
+  derives a tandem duplication.
+- Insertions over deleted reference bases and deletions with inserted bases now emit both variants instead of the
+  larger one alone. The smaller component was previously discarded, leaving an allele that reported no inserted
+  sequence.
+- Documentation page describing the VCF output.
+- Config parameter `perf_log` logs the CPU and memory usage of each rule from input assemblies to the VCF to
+  `log/perf/{asm_name}/{rule}_{wildcards}.parquet` (e.g. `log/perf/HG00171/call_intra_snv_insdel_h1.parquet`).
+  `true` takes a snapshot every 30 seconds, a positive integer sets the seconds between snapshots, and `false` or `0`
+  (default) disables it. The table is rewritten after every snapshot, so a job killed for exceeding its memory keeps
+  its samples. Adjunct rules (tracks, alignment depth) are not logged.
+- Runtime dependencies PyYAML, for `pav.yaml`, and psutil, for `perf_log`.
+- Workflow targets `callable`, the callable regions of each haplotype, and `tracks_var`, the variant tracks of each
+  haplotype.
+
+### Removed
+- **Breaking:** Snakemake `benchmark` directives (`log/benchmark/`), replaced by `perf_log`.
+- **Breaking:** VCF `INFO/SVTYPE`. VCF 4.5 deprecates it as redundant with ALT, which carries the type in the
+  symbolic allele or in the REF and ALT lengths.
+- The `##FILTER=<ID=PASS>` header. VCF defines PASS implicitly.
+- Workflow target `align_export_all`. It always failed in PAV 3, which does not yet implement the alignment export
+  rule it requires.
+
+### Fixed
+- Alignment trimming truncated the passing alignment instead of the filtered one where a passing and a filtered
+  alignment overlapped (the filtered flag was inverted).
+- Alignment trimming applied the left-aligning tie-break to alignments in opposite orientations instead of
+  alignments in the same orientation.
+- Alignment trimming removed a passing alignment contained in a higher-scoring filtered alignment. The filtered
+  alignment is now removed.
+- The haplotype merge dropped one of two variants with the same position, end, and length on one haplotype (e.g. a
+  1 bp insertion and deletion at one site). Duplicates are now identified with the variant type and sequence.
+- Symbolic VCF records (INV, DUP) had the first base of the variant as `REF` instead of the base at `POS`.
+- VCF FORMAT keys and sample values were separated by `;` instead of `:`.
+- An unknown `lc_model` name is an error instead of silently disabling LC filtering (path-like names) or raising an
+  unrelated import error (plain names).
+- Variant IDs were duplicated when a variant merged into both the passing and non-passing haplotype merges. IDs
+  are now versioned across both merges rather than within each.
+- Deletions derived from complex variants were written with an empty VCF `REF`.
+- Insertions at a tandem duplication were written with `REF` matching `ALT`, encoding no variant.
+- Writing a VCF now fails, naming the variants, if a record has an empty `REF`, an empty `ALT`, or a `REF`
+  matching its `ALT`.
+- Query homology was read from the reference homology field.
+- VCF `INFO/DUP` was dropped for variants duplicating an even number of regions.
+- `DUP` and `CPX` records carried no `INFO/END`, so they indexed as 1 bp and could be missed by region queries.
+- Large deletions reported an empty query region, which wrote `INFO/QUERY` as an inverted range. Deletions now
+  report a 1 bp query region at the breakpoint, matching intra-alignment deletions. Query homology is still
+  measured over the query region between the anchors.
+- Complex variants reported the query region between the untrimmed anchors, which excludes bases duplicated at
+  the variant site, leaving `INFO/QUERY` shorter than `INFO/SVLEN`. They now report the region from the
+  query-reference-trimmed alignments, as insertions do, when that region spans the duplicated bases.
+- Insertions and complex variants took the duplicated bases at the variant site from the query region of the
+  query-reference-trimmed alignments without checking that reference trimming resolved the overlap between the
+  anchors. Where it did not, a tandem duplication was written with no sequence at all. The duplicated bases are
+  again read from the reference in that case, and the variant reports a 1 bp query region rather than an empty
+  one.
+- Perfect homology was reported as zero when it ran to the end of the compared flank, understating `INFO/HOMLEN`
+  for short variants in low-complexity sequence.
+- The assertion comparing the query-trimmed and query-reference-trimmed reference regions of an alignment
+  interval joined its conditions with `or`, so it passed whenever any one of them held.
+- INV/DUP/CPX tracks failed to build with `Trailing characters parsing integer in field 7` once the duplication
+  callset carried duplications derived from insertions. Duplications are the only records without their own
+  thick-line coordinates, and the missing values were filled with the literal text `pos` and `end` instead of the
+  variant position, which `bedToBigBed` rejected.
+- Track columns typed as numbers in the AutoSQL table are now checked before the BED is written, naming the
+  column rather than failing inside `bedToBigBed`. UCSC itemRgb columns, which are declared `uint` but hold
+  `R,G,B` strings, are exempt.
+- Duplication filters were assigned to the wrong records. The duplication table sorted its filter column on its
+  own rather than the codes within each record, moving filters such as `LCALIGN` and `MAPQ` between duplications.
+- Duplication IDs were not unique. Derived duplications of the same reference region (e.g. a region copied twice by
+  one complex variant) shared one ID, because the duplication table was written without the ID versioning applied
+  to the other tables. Repeated IDs now take a version suffix (`.1`, `.2`), and passing variants keep the
+  unversioned ID.
+- Variant IDs changed after other records were linked to them. IDs were versioned as each call source was
+  integrated, when the `derived`, `discord`, and `inner` columns and the complex variant segment and reference trace
+  tables link to them, then versioned again when the table was written, which reassigned versions among variants
+  sharing an ID. IDs are now versioned once. Variants derived from other variants are versioned last, so they never
+  take an ID another record links to. A passing variant takes a versioned ID when a variant integrated before it has
+  the same ID (e.g. an alignment-truncating deletion filtered by `LCALIGN` keeps its ID over a passing deletion at
+  the same site).
+- Complex variants whose sequence matches the reference bases they replace were written with REF equal to ALT when
+  the reference was soft-masked, because the check compared case. They are left out of the VCF with a warning.
+- VCF `INFO/SUBTYPE`, `INFO/CPX_REF_TRACE`, and `INFO/CPX_QRY_TRACE` were written with an empty value for complex
+  variants with an empty reference or query trace.
+- VCF records were written with CSV quoting: an empty INFO column was written as `""`, and a value containing a
+  quote was wrapped in quotes. An empty INFO column is now `.`.
+- With `vcf_haplotypes`, variants carried only by haplotypes left out of the VCF were written with no haplotype
+  carrying the ALT allele (e.g. `0|0`).
+- `pav3 license` without a format argument failed instead of printing the brief license.
+
+## 3.0.0.dev26 - 2026-08-28
+
+### Changed
+- Version bump to mitigate version conflicts with built containers with a stale version number.
+
+## 3.0.0.dev25 - 2026-08-28
+
+### Added
+- `lift`, `subseq`, and `maketable` subcommands.
+
+### Changed
+- Repository moved to BeckLaboratory/pav3 and images deployed to GHCR.
+- Updated Agglovar version and merge fields.
+- Documentation fixes for Read the Docs and a callout about container permissions.
+
+### Fixed
+- `pav3.workflow.link_fasta()` returned an empty list for uncompressed FASTA files.
+
+## 3.0.0.dev23 - 2026-06-18
+
+### Added
+- Docker and Apptainer build processes.
+
+### Changed
+- Routines locating PAV resources accept a path other than the working directory.
+- Updated Polars and other dependency versions.
+
+### Fixed
+- Workaround for a Polars 1.41 streaming bug.
+
+## 3.0.0.dev22 - 2026-05-06
+
+### Added
+- Functions converting alignment operations to sequence operations (`M` to `=`/`X`).
+
+### Changed
+- VCF writing supports multiple samples.
+- Schema harmonized with Agglovar.
+
+### Fixed
+- Reading `M` alignment operations from SAM files.
+- Intra-alignment variant performance.
+- `from_definition` typo.
+
+## 3.0.0.dev21 - 2026-03-30
+
+### Fixed
+- Off-by-one error lifting regions.
+- Float32/Float64 mismatch with Polars 1.38 and newer.
+- Snakemake `namedlist` import location varies by version.
+
+## 3.0.0.dev20 - 2026-03-23
+
+### Changed
+- Genotype procedure supports multi-sample merges.
+- Removed Snakemake from `rules/align.smk`.
+
+### Fixed
+- VCF irregularities.
+
+## 3.0.0.dev19 - 2026-03-19
+
+### Changed
+- Tuned inter-alignment variant models for robustness.
+- Score model accepts n template switches.
+- `integrate_sources` moved from Snakemake into a library routine.
+
+### Fixed
+- Inter-alignment variant discovery and scoring model bugs.
+- Interval reported the absolute value for `ref_len`, which is negative for a tandem duplication at a breakpoint.
+- Float32/Float64 type mismatch between NumPy and Polars.
+
+## 3.0.0.dev18 - 2026-02-18
+
+### Fixed
+- Complex variant structures, including duplications at a breakpoint.
+- VCF failures with empty variant tables.
+- Dependabot vulnerability alert.
+
+## 3.0.0.dev17 - 2026-02-10
+
+### Fixed
+- Missing inversion schema for intra-alignment inversions with no variants.
+
+## 3.0.0.dev16 - 2026-02-09
+
+### Changed
+- Schema cast sorts columns by schema order.
+
+### Fixed
+- Intra-alignment inversion discovery.
+- Dependabot alerts (urllib3, filelock, virtualenv).
+
+## 3.0.0.dev15 - 2026-02-08
+
+### Added
+- Variant and alignment tracks.
+- Tools for interactive development and troubleshooting.
+- Configuration file flexibility.
+
+### Changed
+- Reworked the workflow framework.
+- Alignment lift framework rewritten for efficiency.
+
+### Fixed
+- Inversion detection, including false negatives around alignment breaks with no aligned inverted segment.
+- Intra-alignment variant calling and coordinate lifts.
+- Variant sort order at intermediate stages.
+- Variant table schema mismatches.
+
+## 3.0.0.dev14 - 2025-12-08
+
+### Changed
+- Semicolons are converted when writing VCFs.
+
+## 3.0.0.dev13 - 2025-12-05
+
+### Added
+- VCF writer.
+
+### Changed
+- `call` subcommand renamed to `batch`.
+- Configuration file renamed from `config.json` to `pav.json`, with a warning for the old name.
+
+## 3.0.0.dev12 - 2025-11-27
+
+### Fixed
+- Inversion flag bugs.
+- Errors from PAV and Agglovar versions getting out of sync.
+
+## 3.0.0.dev11 - 2025-11-26
+
+### Changed
+- Updated Agglovar version.
+
+## 3.0.0.dev10 - 2025-11-26
+
+### Added
+- Complex variants in the haplotype merge (`results/{asm_name}/call/call_cpx.parquet`).
+
+### Changed
+- Replaced the `polars-u64-idx` dependency with `polars` 1.35.2 or newer.
+
+## 3.0.0.dev9 - 2025-11-20
+
+### Added
+- Haplotype merge combining the per-haplotype call tables of an assembly into
+  `results/{asm_name}/call/call_{vartype}.parquet` for INS/DEL, INV, and SNV, merging passing and filtered variants
+  separately. Merge parameters are in `pav3.const.DEFAULT_MERGE_PARAMS`.
+
+### Changed
+- Large insertion and tandem duplication tables replace the `ref_templ` column with `dup`, the duplicated reference
+  loci. Complex variant tables add `seg`, the aligned segments between the anchors, and `dup`.
+- Large variants are sorted by reference position before they are resolved, speeding sequence and homology lookups.
+- Updated Agglovar version.
+
+## 3.0.0.dev8 - 2025-11-06
+
+### Changed
+- Variant ID expressions moved to Agglovar.
+
+### Fixed
+- QC routines causing inversion loss.
+- Build not finding PAV files.
+
+## 3.0.0.dev6, 3.0.0.dev7 - 2025-10-21
+
+### Fixed
+- Removed a line raising `NotImplementedError`.
+
+## 3.0.0.dev5 - 2025-10-21
+
+### Changed
+- Haplotype variant tables relocated.
+
+### Fixed
+- Variant table handling.
+
+## 3.0.0.dev4 - 2025-10-08
+
+### Added
+- Command-line interface.
+- `CONTRIBUTING.md`.
+
+### Changed
+- Package data relocated and packaging updated for upload.
+
+## 3.0.0.dev3 - 2025-10-06
+
+### Added
+- PAV 3 complete through haplotype call tables (rule `call_tables_hap`).
+
+## 3.0.0.dev2 - 2025-06-23
+
+### Added
+- Low-confidence alignment prediction model for filtering alignment records.
+- QC for large SV calling and tracks.
+
+### Changed
+- Alignment trimming performance for deep overlapping alignment records.
+- Reworked feature handling and alignment operation handling.
+- CIGAR and non-large inversion calls integrated with PAV 3.
+- I/O avoids pysam, which breaks on large operation lengths.
+- Renamed `.snakemake` files to `.smk`.
+
+### Removed
+- `keep-going` from the default Snakemake profiles.
+
+### Fixed
+- Large variant calls and alignment filter aliases.
+
+## 3.0.0.dev1 - 2024-12-22
+
+### Changed
+- Altered PAV project structure including library.
+- Replaced Pandas with Polars.
+- Increased performance with Polars and vectorization.
+- Repository transitioned to the Beck laboratory.
+
+### Added
+- Variant intersects are handled by agglovar.
+
+### Removed
+- SVPop was replaced by agglovar and some functions were moved into PAV.

pav3-3.0.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,109 @@
+
+# Contributor Covenant 3.0 Code of Conduct
+
+## Our Pledge
+
+We pledge to make our community welcoming, safe, and equitable for all.
+
+We are committed to fostering an environment that respects and promotes the dignity, rights, and contributions of all
+individuals, regardless of characteristics including race, ethnicity, caste, color, age, physical characteristics,
+neurodiversity, disability, sex or gender, gender identity or expression, sexual orientation, language, philosophy or
+religion, national or social origin, socio-economic position, level of education, or other status. The same privileges
+of participation are extended to everyone who participates in good faith and in accordance with this Covenant.
+
+## Encouraged Behaviors
+
+While acknowledging differences in social norms, we all strive to meet our community's expectations for positive
+behavior. We also understand that our words and actions may be interpreted differently than we intend based on culture,
+background, or native language.
+
+With these considerations in mind, we agree to behave mindfully toward each other and act in ways that center our shared
+values, including:
+
+1. Respecting the **purpose of our community**, our activities, and our ways of gathering.
+2. Engaging **kindly and honestly** with others.
+3. Respecting **different viewpoints** and experiences.
+4. **Taking responsibility** for our actions and contributions.
+5. Gracefully giving and accepting **constructive feedback**.
+6. Committing to **repairing harm** when it occurs.
+7. Behaving in other ways that promote and sustain the **well-being of our community**.
+
+
+## Restricted Behaviors
+
+We agree to restrict the following behaviors in our community. Instances, threats, and promotion of these behaviors are
+violations of this Code of Conduct.
+
+1. **Harassment.** Violating explicitly expressed boundaries or engaging in unnecessary personal attention after any
+   clear request to stop.
+2. **Character attacks.** Making insulting, demeaning, or pejorative comments directed at a community member or group of
+   people.
+3. **Stereotyping or discrimination.** Characterizing anyone’s personality or behavior on the basis of immutable
+   identities or traits.
+4. **Sexualization.** Behaving in a way that would generally be considered inappropriately intimate in the context or
+   purpose of the community.
+5. **Violating confidentiality**. Sharing or acting on someone's personal or private information without their
+   permission.
+6. **Endangerment.** Causing, encouraging, or threatening violence or other harm toward any person or group.
+7. Behaving in other ways that **threaten the well-being** of our community.
+
+### Other Restrictions
+
+1. **Misleading identity.** Impersonating someone else for any reason, or pretending to be someone else to evade
+   enforcement actions.
+2. **Failing to credit sources.** Not properly crediting the sources of content you contribute.
+3. **Promotional materials**. Sharing marketing or other commercial content in a way that is outside the norms of the
+   community.
+4. **Irresponsible communication.** Failing to responsibly present content which includes, links or describes any other
+   restricted behaviors.
+
+
+## Reporting an Issue
+
+Tensions can occur between community members even when they are trying their best to collaborate. Not every conflict
+represents a code of conduct violation, and this Code of Conduct reinforces encouraged behaviors and norms that can help
+avoid conflicts and minimize harm.
+
+When an incident does occur, it is important to report it promptly. **Please report violations to
+Peter Audano (peter.audano@jax.org)**. Alternatively, you may consult with Christine Beck (christine.beck@jax.org) or
+The Jackson Laboratory HR department (hrhelp@jax.org) for guidance.
+
+Community Moderators take reports of violations seriously and will make every effort to respond in a timely manner. They
+will investigate all reports of code of conduct violations, reviewing messages, logs, and recordings, or interviewing
+witnesses and other participants. Community Moderators will keep investigation and enforcement actions as transparent as
+possible while prioritizing safety and confidentiality. In order to honor these values, enforcement actions are carried
+out in private with the involved parties, but communicating to the whole community may be part of a mutually agreed upon
+resolution.
+
+
+## Addressing Violations
+
+****
+
+Complaints will be reviewed confidentially and appropriate responses will be taken including suspension and
+permanent bans from the project as necessary. We reserve the right to remove any content contributed by a violator
+including code and discussions. 
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing
+the community in public or other spaces. Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed representative at an online or offline event.
+
+
+## Attribution
+
+This Code of Conduct is adapted from the Contributor Covenant, version 3.0, permanently available at
+[https://www.contributor-covenant.org/version/3/0/](https://www.contributor-covenant.org/version/3/0/).
+
+Contributor Covenant is stewarded by the Organization for Ethical Source and licensed under CC BY-SA 4.0. To view a copy
+of this license, visit [https://creativecommons.org/licenses/by-sa/4.0/](https://creativecommons.org/licenses/by-sa/4.0/)
+
+For answers to common questions about Contributor Covenant, see the FAQ at
+[https://www.contributor-covenant.org/faq](https://www.contributor-covenant.org/faq). Translations are provided at
+[https://www.contributor-covenant.org/translations](https://www.contributor-covenant.org/translations). Additional enforcement and community guideline resources can
+be found at [https://www.contributor-covenant.org/resources](https://www.contributor-covenant.org/resources). The enforcement ladder was inspired by the work of
+[Mozilla’s code of conduct team](https://github.com/mozilla/inclusion).
+
+Some modifications to the original code of conduct were made using the
+[Atom project Code of Conduct](https://github.com/atom/atom/blob/master/CODE_OF_CONDUCT.md) as a guide.

pav3-3.0.0/CONTRIBUTING.md

@@ -0,0 +1,146 @@
+# Contributing
+
+Thank you for your interest in contributing! We appreciate your help including bugs reports and implementing new
+features.
+
+## Bugs, questions, and feature requests
+
+The project's [GitHub issues page](https://github.com/BeckLaboratory/pav3/issues) may be used to ask questions,
+report bugs, and request features.
+
+Please search for related issues before opening a new one. If you find a relevant open issue, you may monitor it for
+updates (look for the "Subscribe" button on the issue's page). Add comments to existing issues as needed. Reference
+related issues in your new issue or comments. Comments on closed issues may be missed.
+
+Please make sure you understand the [Code of Conduct](CODE_OF_CONDUCT.md) before opening or commenting on issues.
+
+### Reporting bugs
+
+When reporting a bug, please provide the following information:
+* A clear and concise description of the bug.
+* The version of the project you are using.
+* The steps to reproduce the bug.
+* Any error messages you receive.
+* Platform information (e.g. OS, Python version, etc).
+
+Please include as many details as possible in your report, it helps us resolve the issue faster. Please also take a
+moment to re-read your report to ensure it is clear and concise. When in doubt, more detail is generally better.
+
+### Feature requests
+
+We welcome ideas for improving on the project. Please provide a clear description of the feature you would like and
+examples about why it is useful. Please help us understand the full context of your feature request so that we can
+make an informed decision and properly prioritize the request.
+
+## Contributing
+
+Bugs are often fixed by the maintainers, but please feel free to look for issues and submit pull requests. Pick any
+issue that is accepted and not assigned to another contributor. You may comment on the issue to express your interest
+in working on it.
+
+If you are a first time contributor, we will do our best to mark issues as a "good first issue".
+
+If you would like to take on an issue, please comment on the issue to let others know. You may use the issue to discuss
+possible solutions.
+
+Please make sure you understand the [Code of Conduct](CODE_OF_CONDUCT.md) before becoming a contributor.
+
+### Setting up your environment
+
+Pull the codebase from GitHub:
+```bash
+git clone https://github.com/BeckLaboratory/pav3.git
+cd pav
+```
+
+A virtual environment is already setup with [uv](https://docs.astral.sh/uv/). See the
+[uv installation guide](https://docs.astral.sh/uv/getting-started/installation/) to install uv if you do not have it.
+
+Initialize your virtual environment:
+```bash
+uv sync
+```
+
+This will create a virtual environment in the `.venv` directory including all project dependencies and development tools
+used directly by this project. Your IDE can use the virtual environment to provide features such as code completion.
+
+Commands in the virtual environment can be run by prefixing them with `uv`.
+
+Open an interactive session:
+```bash
+uv run ipython
+```
+
+### Setting up your IDE
+
+This project was developed with [PyCharm](https://www.jetbrains.com/pycharm/), but no specific IDE is compulsory. When
+opening the projcet in PyCharm, it should detect the uv virtual environment and use it. If not, you may need to
+configure the IDE to use the environment in `.venv`.
+
+### Linting and unit tests
+
+Linting and unit tests are setup through tox environments [tox](https://tox.wiki/) already configured for this project.
+A list of environments can be viewed in [tox.toml]. Environments starting with "py" are for unit testing various
+Python versions, and a "flake8" environment is for linting. By default, running a tox environment will run all unit
+tests or perform linting for the whole project.
+
+Important environments are:
+* flake8: Linting.
+* sphinx: Build documentation.
+
+
+To run a tox environment, use:
+```bash
+uv run tox -e <environment_name>
+```
+
+For example, to run the linting environment:
+```bash
+uv run tox -e flake8
+```
+
+The same tools are also available in the virtual environment and can be run with the `uv` prefix.
+
+For example, lint a single file:
+```bash
+uv run flake8 <file_path>
+```
+
+Please ensure your contributions pass linting and do not break unit tests before submitting a pull request. When adding
+a new feature, please consider adding unit tests for it.
+
+
+### Pull requests
+
+When your contribution is ready, open a pull request.
+
+Before submitting a pull request:
+* Make sure your changes are rebased against the main branch.
+* Ensure your code is free of linting errors (See [Linting and unit tests])
+* Ensure your code does not break any existing unit tests (See [Linting and unit tests]).
+* Ensure your code follows the conventions outlined in the [Conventions](#conventions) section.
+
+While submitting a pull request:
+* Use a clear and concise title.
+* Provide a clear and concise description.
+* Reference the issue(s) you are working on.
+
+A maintainer will review your request and may ask for changes or leave comments. Once all issues are resolved, the
+pull request will be merged into the main branch, and your contribution will be included in the next release!
+
+If you are stuck or unsure about your solution, feel free to open a draft pull request and ask for help.
+
+## Conventions
+
+* Use [reStructuredText docstrings](https://sphinx-rtd-tutorial.readthedocs.io/en/latest/docstrings.html)
+  * Omit ":type:" and ":rtype:", allow type hints to fill it in.
+* Use type hints.
+* Use snake_case for variable names and function names.
+* Use CamelCase for class names.
+* Line length limit 120 characters
+* Use 4 spaces for indentation.
+* Place operators at the start of multi-line expressions rather than the end.
+* Avoid backslashes, enclose in parethesis instead.
+* All non-public members should be prefixed with an underscore.
+* All public package members must appear in __all__.
+* Use relative imports except for a few submodules with no dependencies on other submodules.