### Install pgscatalog-match

Source: https://github.com/pgscatalog/pygscatalog/blob/main/docs/how-to/guides/match.rst

Install the pgscatalog-match package using pip. This command installs the CLI tool and its dependencies.

```bash
pip install pgscatalog-match
```

--------------------------------

### Install pgscatalog.core via pipx

Source: https://github.com/pgscatalog/pygscatalog/blob/main/pgscatalog.utils/packages/pgscatalog.core/README.md

Use pipx to install the package globally.

```bash
$ pipx install pgscatalog.core
```

--------------------------------

### Install pygscatalog dependencies

Source: https://github.com/pgscatalog/pygscatalog/blob/main/docs/how-to/guides/validate.rst

Clone the repository and install required dependencies using poetry.

```bash
$ git clone https://github.com/PGScatalog/pygscatalog.git
$ cd pygscatalog/pygscatalog.validate
```

```bash
$ poetry install
```

--------------------------------

### Install pgscatalog-core

Source: https://github.com/pgscatalog/pygscatalog/blob/main/docs/how-to/guides/download.rst

Install the pgscatalog-core package using pip.

```bash
pip install pgscatalog-core
```

--------------------------------

### Install pgscatalog-core

Source: https://github.com/pgscatalog/pygscatalog/blob/main/docs/how-to/guides/format.rst

Install the core package containing the formatting tools via pipx.

```bash
$ pipx install pgscatalog-core
```

--------------------------------

### Install package via pip

Source: https://github.com/pgscatalog/pygscatalog/blob/main/docs/how-to/guides/validate.rst

Build the wheel package and install it into the current environment.

```bash
$ poetry build
```

```bash
$ pip install dist/pgscatalog_validate-0.1-py3-none-any.whl
```

```bash
pgscatalog-validate --help
```

--------------------------------

### Install pgscatalog.match with pipx

Source: https://github.com/pgscatalog/pygscatalog/blob/main/pgscatalog.utils/packages/pgscatalog.match/README.md

Use pipx to install the pgscatalog.match package globally. This is a recommended method for installing Python CLI applications.

```bash
$ pipx install pgscatalog.match
```

--------------------------------

### Set up development environment with nox

Source: https://github.com/pgscatalog/pygscatalog/blob/main/pgscatalog.utils/packages/pgscatalog.match/README.md

Use nox to set up a development environment. This command creates a virtual environment and installs necessary dependencies.

```bash
$ nox -s dev
```

--------------------------------

### Install pgscatalog.calc via pipx

Source: https://github.com/pgscatalog/pygscatalog/blob/main/pgscatalog.utils/packages/pgscatalog.calc/README.md

Use pipx to install the package in an isolated environment.

```bash
$ pipx install pgscatalog.calc
```

--------------------------------

### Install pgscatalog-validate Package

Source: https://context7.com/pgscatalog/pygscatalog/llms.txt

Install the pgscatalog-validate package from source using pip.

```bash
pip install pgscatalog-validate
```

--------------------------------

### Install pgscatalog-calc

Source: https://github.com/pgscatalog/pygscatalog/blob/main/docs/how-to/guides/aggregate.rst

Install the pgscatalog-calc package using pip. This command installs the necessary tools for managing and aggregating PGS data.

```bash
pip install pgscatalog-calc
```

--------------------------------

### Install pgscatalog-utils via pipx

Source: https://github.com/pgscatalog/pygscatalog/blob/main/pgscatalog.utils/README.md

Use pipx to install the package globally in an isolated environment.

```bash
$ pipx install pgscatalog-utils
```

--------------------------------

### Install PyGSCatalog Package

Source: https://github.com/pgscatalog/pygscatalog/blob/main/pgscatalog.validate/README.md

Install the built wheel package into the current Python environment using pip. This command assumes the wheel file is in the 'dist' directory.

```bash
# Install the built package in the current environment via pip
$ pip install dist/pgscatalog_validate-0.1-py3-none-any.whl
```

--------------------------------

### Get pgscatalog-match Help

Source: https://github.com/pgscatalog/pygscatalog/blob/main/docs/how-to/guides/match.rst

Display the help message for the pgscatalog-match CLI tool to see all available options and commands.

```bash
pgscatalog-match --help
```

--------------------------------

### Download Scoring File

Source: https://context7.com/pgscatalog/pygscatalog/llms.txt

Download a scoring file to a specified directory. This example uses a temporary directory.

```python
from pgscatalog.core.lib import ScoringFile, GenomeBuild
import tempfile

# Download to directory
with tempfile.TemporaryDirectory() as tmp_dir:
    sf.download(tmp_dir)
    # Creates: PGS000001_hmPOS_GRCh38.txt.gz
```

--------------------------------

### Build PyGSCatalog Wheel Package

Source: https://github.com/pgscatalog/pygscatalog/blob/main/pgscatalog.validate/README.md

Use the nox build command to create a wheel package for the PyGSCatalog. This is a prerequisite for installing the package.

```bash
# Build the wheel package
$ nox -s build
```

--------------------------------

### Activate virtual environment

Source: https://github.com/pgscatalog/pygscatalog/blob/main/pgscatalog.utils/packages/pgscatalog.match/README.md

Activate the virtual environment created by nox. This ensures that subsequent commands use the correct Python interpreter and installed packages.

```bash
$ source .venv/bin/activate
```

--------------------------------

### Get PGS Catalog Query URL

Source: https://context7.com/pgscatalog/pygscatalog/llms.txt

Generate the URL for a PGS Catalog API query, useful for debugging or understanding the request.

```python
from pgscatalog.core.lib import CatalogQuery, CatalogCategory

# Get query URL for debugging
print(query.get_query_url())
# 'https://www.pgscatalog.org/rest/trait/EFO_0001645?include_children=1'
```

--------------------------------

### Normalize Scoring File Variants

Source: https://context7.com/pgscatalog/pygscatalog/llms.txt

Normalize scoring file variants to extract key fields and perform quality control. This example prints the effect type.

```python
from pgscatalog.core.lib import ScoringFile, GenomeBuild

# Normalise scoring file (extracts key fields, does QC)
for variant in sf.normalise():
    print(f"{variant.rsID}: {variant.effect_type}")
    break
```

--------------------------------

### Initialize development environment

Source: https://github.com/pgscatalog/pygscatalog/blob/main/pgscatalog.utils/README.md

Set up the development environment using nox and activate the virtual environment.

```bash
$ nox -s dev
$ source .venv/bin/activate
```

--------------------------------

### Clone and Set Up PyGSCatalog Development Environment

Source: https://github.com/pgscatalog/pygscatalog/blob/main/pgscatalog.validate/README.md

Clone the repository, navigate to the directory, and use nox to create a development environment. Activate the virtual environment using the provided command.

```bash
# Download the source code
$ git clone https://github.com/PGScatalog/pygscatalog.git
$ cd pygscatalog/pgscatalog.validate
$ nox -s dev
$ source .venv/bin/activate
```

--------------------------------

### Display help for pgscatalog-download

Source: https://github.com/pgscatalog/pygscatalog/blob/main/pgscatalog.utils/README.md

Access the help documentation for the download utility.

```bash
$ pgscatalog-download --help
```

--------------------------------

### Display help information

Source: https://github.com/pgscatalog/pygscatalog/blob/main/docs/how-to/guides/format.rst

Access the command-line help documentation for pgscatalog-format.

```bash
$ pgscatalog-format --help
```

--------------------------------

### Run pgscatalog-validate in virtual environment

Source: https://github.com/pgscatalog/pygscatalog/blob/main/docs/how-to/guides/validate.rst

Activate the virtual environment and display help information.

```bash
$ poetry shell
$ pgscatalog-validate --help
```

--------------------------------

### Display aggregate help

Source: https://github.com/pgscatalog/pygscatalog/blob/main/pgscatalog.utils/packages/pgscatalog.calc/README.md

View the help documentation for the pgscatalog-aggregate CLI tool.

```bash
$ pgscatalog-aggregate --help
```

--------------------------------

### Display CLI help

Source: https://github.com/pgscatalog/pygscatalog/blob/main/docs/how-to/guides/validate.rst

Show the help menu for the validation tool.

```bash
$ pgscatalog-validate --help
```

--------------------------------

### Display Help for pgscatalog-download

Source: https://github.com/pgscatalog/pygscatalog/blob/main/docs/how-to/guides/download.rst

View the help message for the pgscatalog-download CLI to understand all available options and commands.

```bash
pgscatalog-download --help
```

--------------------------------

### Run pgscatalog-match help command

Source: https://github.com/pgscatalog/pygscatalog/blob/main/pgscatalog.utils/packages/pgscatalog.match/README.md

Execute the --help flag on the pgscatalog-match CLI to view available commands and options. This is useful for understanding the tool's capabilities.

```bash
$ pgscatalog-match --help
```

--------------------------------

### Run tests and linting

Source: https://github.com/pgscatalog/pygscatalog/blob/main/pgscatalog.utils/packages/pgscatalog.calc/README.md

Execute the default nox session to run tests and lint the package.

```bash
$ nox
```

--------------------------------

### Display Help for pgscatalog-ancestry-adjust

Source: https://github.com/pgscatalog/pygscatalog/blob/main/docs/how-to/guides/aggregate.rst

View the help message for the pgscatalog-ancestry-adjust command to understand all available options and their usage.

```bash
pgscatalog-ancestry-adjust --help
```

--------------------------------

### Download PGS IDs Scoring Files

Source: https://github.com/pgscatalog/pygscatalog/blob/main/docs/how-to/guides/download.rst

Download scoring files for specified PGS IDs aligned to a specific genome build. Ensure the 'downloads' directory exists.

```bash
mkdir downloads
pgscatalog-download --pgs PGS000822 PGS001229 --build GRCh38 -o downloads
```

--------------------------------

### Initialize ScoringFile from Local Path

Source: https://context7.com/pgscatalog/pygscatalog/llms.txt

Create a ScoringFile object from a local file path. Access metadata like header, PGS ID, genome build, and harmonized status.

```python
from pgscatalog.core.lib import ScoringFile, GenomeBuild

# Create from local path
sf = ScoringFile("PGS000001_hmPOS_GRCh38.txt.gz")
print(sf.header)  # CatalogScoreHeader with metadata
print(sf.pgs_id)  # 'PGS000001'
print(sf.genome_build)  # GenomeBuild.GRCh38
print(sf.is_harmonised)  # True
```

--------------------------------

### Initialize ScoringFiles from Multiple PGS IDs

Source: https://context7.com/pgscatalog/pygscatalog/llms.txt

Create a ScoringFiles object by providing multiple PGS IDs directly or as a list.

```python
from pgscatalog.core.lib import ScoringFiles, GenomeBuild

# Create from multiple PGS IDs
scores = ScoringFiles("PGS000001", "PGS000002")

# Create from list
scores = ScoringFiles(["PGS000001", "PGS000002"])
```

--------------------------------

### Initialize ScoringFile

Source: https://context7.com/pgscatalog/pygscatalog/llms.txt

Basic initialization of a ScoringFile object.

```python
sf = ScoringFile("PGS000001", target_build=GenomeBuild.GRCh38)
```

--------------------------------

### Display pgscatalog-intersect Help

Source: https://github.com/pgscatalog/pygscatalog/blob/main/docs/how-to/guides/intersect.rst

View the help message for the pgscatalog-intersect command to understand all available options and parameters.

```bash
pgscatalog-intersect --help
```

--------------------------------

### Initialize ScoringFiles from Trait ID

Source: https://context7.com/pgscatalog/pygscatalog/llms.txt

Create a ScoringFiles object from a trait ID, with an option to include or exclude child traits.

```python
from pgscatalog.core.lib import ScoringFiles, GenomeBuild

# Create from trait ID (includes child traits by default)
scores_with_children = ScoringFiles("MONDO_0004975", include_children=True)
scores_without_children = ScoringFiles("MONDO_0004975", include_children=False)
```

--------------------------------

### Initialize ScoringFiles from Publication ID

Source: https://context7.com/pgscatalog/pygscatalog/llms.txt

Create a ScoringFiles object from a publication ID to retrieve all associated scoring files. Specify the target genome build.

```python
from pgscatalog.core.lib import ScoringFiles, GenomeBuild

# Create from publication ID (returns all associated scores)
scores = ScoringFiles("PGP000001", target_build=GenomeBuild.GRCh37)
print(scores)  # ScoringFiles('PGS000001', 'PGS000002', 'PGS000003', ...)
```

--------------------------------

### Combine scoring files

Source: https://github.com/pgscatalog/pygscatalog/blob/main/docs/how-to/guides/format.rst

Standardize and combine multiple scoring files into a single output directory.

```bash
$ mkdir output
$ pgscatalog-combine -s PGS000001_hmPOS_GRCh38.txt.gz PGS0001229_hmPOS_GRCh38.txt.gz -t GRCh38 -o output
```

--------------------------------

### Initialize ScoringFile from PGS Catalog Accession

Source: https://context7.com/pgscatalog/pygscatalog/llms.txt

Create a ScoringFile object by specifying the PGS Catalog accession ID and target genome build.

```python
from pgscatalog.core.lib import ScoringFile, GenomeBuild

# Create from PGS Catalog accession
sf = ScoringFile("PGS000001", target_build=GenomeBuild.GRCh38)
```

--------------------------------

### Download Scoring Files with pgscatalog-download

Source: https://context7.com/pgscatalog/pygscatalog/llms.txt

Use this command to download scoring files from the PGS Catalog. It supports downloading by PGS ID, EFO trait, or publication ID, with options for specifying genome builds and excluding child traits.

```bash
mkdir downloads
pgscatalog-download --pgs PGS000822 PGS001229 --build GRCh38 -o downloads
```

```bash
pgscatalog-download --efo MONDO_0004975 -b GRCh38 -o downloads
```

```bash
pgscatalog-download --pgp PGP000517 -b GRCh38 -o downloads
```

```bash
pgscatalog-download --efo MONDO_0004975 -b GRCh38 -o downloads --efo_direct
```

--------------------------------

### Download Scores for a Trait (Direct Only)

Source: https://github.com/pgscatalog/pygscatalog/blob/main/docs/how-to/guides/download.rst

Download scoring files associated only with the specified EFO trait accession, excluding child traits. Ensure the 'downloads' directory exists.

```bash
mkdir downloads
pgscatalog-download --efo MONDO_0004975 -b GRCh38 -o downloads --efo_direct
```

--------------------------------

### Match Variants with pgscatalog-match

Source: https://github.com/pgscatalog/pygscatalog/blob/main/docs/how-to/guides/match.rst

Basic usage of the pgscatalog-match CLI to match variants. Specify the dataset, score files, target variant file, output directory, and minimum overlap threshold.

```bash
mkdir matchout
pgscatalog-match --dataset test --scorefiles normalised_scorefile.txt --target variants.pvar --outdir matchout --min_overlap 0.75
```

--------------------------------

### Liftover scoring files

Source: https://github.com/pgscatalog/pygscatalog/blob/main/docs/how-to/guides/format.rst

Combine scoring files across different genome builds using a specified chain file directory.

```bash
$ mkdir output
$ pgscatalog-format -s PGS000001_hmPOS_GRCh38.txt.gz my_scorefile_grch37.txt.gz \
    --chain_dir my_chain_dir/ \
    -t GRCh38 \
    -o output
```

--------------------------------

### Iterate and Download Multiple Scoring Files

Source: https://context7.com/pgscatalog/pygscatalog/llms.txt

Iterate through a ScoringFiles object and download each scoring file to a specified directory.

```python
from pgscatalog.core.lib import ScoringFiles, GenomeBuild

# Iterate and download
for sf in scores:
    print(f"Downloading {sf.pgs_id}")
    sf.download("downloads/")
```

--------------------------------

### Download All Scores for a Trait

Source: https://github.com/pgscatalog/pygscatalog/blob/main/docs/how-to/guides/download.rst

Download all scoring files associated with a given EFO trait accession, harmonized to a specified genome build. Child traits are included by default.

```bash
mkdir downloads
pgscatalog-download --efo MONDO_0004975 -b GRCh38 -o downloads
```

--------------------------------

### Configure Ancestry Adjustment Arguments

Source: https://context7.com/pgscatalog/pygscatalog/llms.txt

Configures parameters for genetic ancestry comparison and PGS normalization using the AdjustArguments class.

```python
from pgscatalog.calc.lib import AdjustArguments

# Default arguments (RandomForest comparison, multiple normalization methods)
args = AdjustArguments()

# Custom arguments
args = AdjustArguments(
    method_compare="Mahalanobis",  # or "RandomForest"
    pThreshold=0.05,  # P-value threshold for ancestry assignment
    method_normalization=("empirical", "mean")  # Normalization methods
)

# Use with adjust()
results = agg_pgs.adjust(ref_pc=ref_pc, target_pc=target_pc, adjust_arguments=args)
```

--------------------------------

### Python Library: pgscatalog.core.lib

Source: https://context7.com/pgscatalog/pygscatalog/llms.txt

Provides classes for working with PGS Catalog scoring files and querying the API.

```APIDOC
## Python Library: pgscatalog.core.lib

### ScoringFile: Work with Individual Scoring Files

Represents a single scoring file with methods for downloading, reading, and normalizing.

```python
from pgscatalog.core.lib import ScoringFile, GenomeBuild

# Create from local path
sf = ScoringFile("PGS000001_hmPOS_GRCh38.txt.gz")
print(sf.header)  # CatalogScoreHeader with metadata
print(sf.pgs_id)  # 'PGS000001'
print(sf.genome_build)  # GenomeBuild.GRCh38
print(sf.is_harmonised)  # True

# Create from PGS Catalog accession
sf = ScoringFile("PGS000001", target_build=GenomeBuild.GRCh38)

# Download to directory
import tempfile
with tempfile.TemporaryDirectory() as tmp_dir:
    sf.download(tmp_dir)
    # Creates: PGS000001_hmPOS_GRCh38.txt.gz

# Iterate over variants
for variant in sf.variants:
    print(f"{variant.rsID}: {variant.chr_name}:{variant.chr_position}")
    print(f"Effect allele: {variant.effect_allele}, Weight: {variant.effect_weight}")
    break

# Normalise scoring file (extracts key fields, does QC)
for variant in sf.normalise():
    print(f"{variant.rsID}: {variant.effect_type}")
    break

# Normalise with liftover
for variant in sf.normalise(liftover=True, chain_dir="chain/", target_build=GenomeBuild.GRCh38):
    print(f"{variant.chr_position}")  # Lifted coordinates
    break
```

### ScoringFiles: Work with Multiple Scoring Files

Container for multiple ScoringFile objects with support for batch operations.

```python
from pgscatalog.core.lib import ScoringFiles, GenomeBuild

# Create from publication ID (returns all associated scores)
scores = ScoringFiles("PGP000001", target_build=GenomeBuild.GRCh37)
print(scores)  # ScoringFiles('PGS000001', 'PGS000002', 'PGS000003', ...)

# Create from multiple PGS IDs
scores = ScoringFiles("PGS000001", "PGS000002")

# Create from list
scores = ScoringFiles(["PGS000001", "PGS000002"])

# Create from trait ID (includes child traits by default)
scores_with_children = ScoringFiles("MONDO_0004975", include_children=True)
scores_without_children = ScoringFiles("MONDO_0004975", include_children=False)

# Concatenate ScoringFiles
combined = ScoringFiles('PGS000001') + ScoringFiles('PGS000002', 'PGS000003')

# Iterate and download
for sf in scores:
    print(f"Downloading {sf.pgs_id}")
    sf.download("downloads/")

# Slice and check membership
first_score = scores[0]
print(first_score in scores)  # True
```

### CatalogQuery: Query the PGS Catalog API

Efficiently query the PGS Catalog API using various accession types.

```python
from pgscatalog.core.lib import CatalogQuery, CatalogCategory

# Query by PGS ID
query = CatalogQuery(accession="PGS000001")
result = query.score_query()
print(result.pgs_id)  # 'PGS000001'
print(result.get_download_url())  # FTP URL for original file
print(result.get_download_url(GenomeBuild.GRCh38))  # URL for harmonised file

# Query multiple PGS IDs (batched automatically)
query = CatalogQuery(accession=["PGS000001", "PGS000002"])
results = query.score_query()  # Returns list of ScoreQueryResult

# Query by publication
query = CatalogQuery(accession="PGP000001")
results = query.score_query()  # Returns all scores from publication

# Query by trait with child traits
query = CatalogQuery(accession="EFO_0001645", include_children=True)
results = query.score_query()

# Get query URL for debugging
print(query.get_query_url())
# 'https://www.pgscatalog.org/rest/trait/EFO_0001645?include_children=1'
```

### GenomeBuild: Genome Build Enumeration

Represents supported genome builds for scoring files.

```python
from pgscatalog.core.lib import GenomeBuild

# Available builds
print(GenomeBuild.GRCh37)
print(GenomeBuild.GRCh38)
```
```

--------------------------------

### Access Genome Build Enumerations

Source: https://context7.com/pgscatalog/pygscatalog/llms.txt

Access the GenomeBuild enumeration to represent supported genome builds like GRCh37 and GRCh38.

```python
from pgscatalog.core.lib import GenomeBuild

# Available builds
print(GenomeBuild.GRCh37)
print(GenomeBuild.GRCh38)
```

--------------------------------

### Download Scores for a Publication

Source: https://github.com/pgscatalog/pygscatalog/blob/main/docs/how-to/guides/download.rst

Download all scoring files associated with a specific publication accession, aligned to a specified genome build. Ensure the 'downloads' directory exists.

```bash
mkdir downloads
pgscatalog-download --pgp PGP000517 -b GRCh38 -o downloads
```

--------------------------------

### Normalize Scoring File with Liftover

Source: https://context7.com/pgscatalog/pygscatalog/llms.txt

Normalize scoring file variants using liftover to a target genome build. Requires a chain directory and specifies the target build. Prints lifted coordinates.

```python
from pgscatalog.core.lib import ScoringFile, GenomeBuild

# Normalise with liftover
for variant in sf.normalise(liftover=True, chain_dir="chain/", target_build=GenomeBuild.GRCh38):
    print(f"{variant.chr_position}")  # Lifted coordinates
    break
```

--------------------------------

### Normalize Scoring Files with ScoringFileFrame

Source: https://context7.com/pgscatalog/pygscatalog/llms.txt

Load and filter normalized scoring files for efficient matching.

```python
from pgscatalog.match.lib import ScoringFileFrame

# Create from normalized scoring file (output of pgscatalog-format)
scorefile = ScoringFileFrame("normalised_scorefile.txt")

# Filter to specific chromosome
scorefile = ScoringFileFrame("normalised_scorefile.txt", chrom="22")

# Use context manager
with scorefile as score_df:
    # score_df is a polars LazyFrame
    print(score_df.collect().shape)
```

--------------------------------

### Validate all scoring files in a directory

Source: https://github.com/pgscatalog/pygscatalog/blob/main/docs/how-to/guides/validate.rst

Validate all files within a specified directory and output logs.

```bash
$ mkdir log
$ pgscatalog-validate -t formatted --dir scores_directory/ --log_dir log/
```

--------------------------------

### Format Scoring Files with pgscatalog-format

Source: https://context7.com/pgscatalog/pygscatalog/llms.txt

This command combines and normalizes scoring files into a consistent schema. It supports liftover between genome builds and can utilize multiple threads for faster processing.

```bash
mkdir output
pgscatalog-format -s PGS000001_hmPOS_GRCh38.txt.gz PGS001229_hmPOS_GRCh38.txt.gz -t GRCh38 -o output
```

```bash
pgscatalog-format -s PGS000001_hmPOS_GRCh38.txt.gz my_scorefile_grch37.txt.gz \
    --chain_dir my_chain_dir/ \
    -t GRCh38 \
    -o output
```

```bash
pgscatalog-format -s *.txt.gz -t GRCh38 -o output --threads 4
```

--------------------------------

### Query PGS Catalog by Trait with Children

Source: https://context7.com/pgscatalog/pygscatalog/llms.txt

Query the PGS Catalog API for a trait ID, with an option to include child traits in the search.

```python
from pgscatalog.core.lib import CatalogQuery, CatalogCategory

# Query by trait with child traits
query = CatalogQuery(accession="EFO_0001645", include_children=True)
results = query.score_query()
```

--------------------------------

### Process and Export Match Results

Source: https://context7.com/pgscatalog/pygscatalog/llms.txt

Filter match results and generate score files or logs.

```python
from pgscatalog.match.lib import MatchResults, MatchResult, ScoringFileFrame

# Load match results
match_result = MatchResult.from_ipc("matches.ipc", dataset="my_data")
results = MatchResults(match_result)

# Write score files for plink2 --score
with ScoringFileFrame("normalised_scorefile.txt") as score_df:
    # Write combined files (all chromosomes in one file per effect type)
    results.write_scorefiles(
        directory="output/",
        score_df=score_df,
        min_overlap=0.75
    )

    # Write split files (one file per chromosome and effect type)
    results.write_scorefiles(
        directory="output_split/",
        score_df=score_df,
        split=True,
        min_overlap=0.75
    )

# Generate detailed variant log
with ScoringFileFrame("normalised_scorefile.txt") as score_df:
    log = results.full_variant_log(score_df)
    print(log.fetch())  # polars DataFrame with match status per variant

# Access match summaries
print(results.summary_log)  # Match rates per score
print(results.filter_summary)  # Filter impact summary
```

--------------------------------

### Adjust PGS using Genetic Ancestry

Source: https://github.com/pgscatalog/pygscatalog/blob/main/docs/how-to/guides/ancestry.rst

Run the `pgscatalog-ancestry-adjust` command-line tool to adjust PGS. Ensure all required input files are provided, including aggregated scores, reference and target PCs, relatedness cutoff, and sample information.

```bash
pgscatalog-ancestry-adjust --agg_scores aggregated_scores.txt.gz \
    --psam reference.psam \
    --ref_pcs ref.pcs \
    --target_pcs target.pcs \
    --reference_related ref.king.cutoff.id \
    --dataset hgdp \
    --reference reference \
    --outdir ancestry_results
```

--------------------------------

### pgscatalog-validate

Source: https://context7.com/pgscatalog/pygscatalog/llms.txt

Validates scoring files against PGS Catalog format standards.

```APIDOC
## pgscatalog-validate

### Description
Validates scoring files against PGS Catalog format standards.

### Method
CLI Command

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
- `--type` (string) - Required - Type of scoring file to validate ('formatted' or 'harmonized').
- `--file` (string) - Optional - Path to a single scoring file to validate.
- `--dir` (string) - Optional - Path to a directory containing scoring files to validate.
- `--log_dir` (string) - Required - Directory to store log files.

#### Request Body
None

### Command Examples
```bash
# Install the package (from source)
pip install pgscatalog-validate

# Validate a single formatted scoring file
mkdir log
pgscatalog-validate -t formatted -f PGS000001.txt.gz --log_dir log/

# Validate harmonized scoring file
pgscatalog-validate -t harmonized -f PGS000001_hmPOS_GRCh38.txt.gz --log_dir log/

# Validate all scoring files in a directory
pgscatalog-validate -t formatted --dir scores_directory/ --log_dir log/
```
```

--------------------------------

### Aggregate PGS Data

Source: https://github.com/pgscatalog/pygscatalog/blob/main/docs/how-to/guides/aggregate.rst

Use pgscatalog-ancestry-adjust to aggregate PGS data from multiple input files. Specify input files with -s, the output prefix with -o, and enable verbose output with --verbose. Input files are expected in plink2 --score output format and can be compressed.

```bash
pgscatalog-ancestry-adjust -s hgdp_14_additive_0.sscore.zst hgdp_17_additive_0.sscore.zst \
    -o aggregated \
    --verbose
```

--------------------------------

### Manage Target Genome Variants with VariantFrame

Source: https://context7.com/pgscatalog/pygscatalog/llms.txt

Create and process target genome variants from plink files using a context manager.

```python
from pgscatalog.match.lib import VariantFrame

# Create from plink variant file
target = VariantFrame("variants.pvar", dataset="my_dataset")
# Also supports .bim files

# Use context manager to prepare dataframe
with target as target_df:
    # target_df is a polars LazyFrame
    print(target_df.collect().shape)  # (num_variants, 6)

# Files are automatically cleaned up after context manager exits
```

--------------------------------

### Match Scoring Files to Target Genomes

Source: https://context7.com/pgscatalog/pygscatalog/llms.txt

Perform variant matching between scoring files and target genomes using context managers.

```python
from pgscatalog.match.lib import VariantFrame, ScoringFileFrame, match_variants, MatchResult

# Set up target and scoring file
target = VariantFrame("variants.pvar", dataset="my_data")
scorefile = ScoringFileFrame("normalised_scorefile.txt")

# Match variants using context managers
import tempfile
fout = tempfile.NamedTemporaryFile(delete=False)

with target as target_df, scorefile as score_df:
    results = match_variants(score_df=score_df, target_df=target_df, target=target)
    # Collect and save results to Arrow IPC file
    results.collect(outfile=fout.name)

# Load results from file
match_result = MatchResult.from_ipc(fout.name, dataset="my_data")
```

--------------------------------

### Slice and Check Membership in ScoringFiles

Source: https://context7.com/pgscatalog/pygscatalog/llms.txt

Access individual ScoringFile objects from a ScoringFiles collection using slicing and check for membership.

```python
from pgscatalog.core.lib import ScoringFiles, GenomeBuild

# Slice and check membership
first_score = scores[0]
print(first_score in scores)  # True
```

--------------------------------

### Query PGS Catalog by Multiple PGS IDs

Source: https://context7.com/pgscatalog/pygscatalog/llms.txt

Query the PGS Catalog API for multiple PGS IDs. The query is automatically batched. Returns a list of ScoreQueryResult objects.

```python
from pgscatalog.core.lib import CatalogQuery, CatalogCategory

# Query multiple PGS IDs (batched automatically)
query = CatalogQuery(accession=["PGS000001", "PGS000002"])
results = query.score_query()  # Returns list of ScoreQueryResult
```

--------------------------------

### match_variants: Match Scoring File to Target Genome

Source: https://context7.com/pgscatalog/pygscatalog/llms.txt

Matches variants between scoring files and target genomes.

```APIDOC
## match_variants

### Description
Matches variants between scoring files and target genomes.

### Usage
```python
from pgscatalog.match.lib import match_variants
with target as target_df, scorefile as score_df:
    results = match_variants(score_df=score_df, target_df=target_df, target=target)
    results.collect(outfile="results.ipc")
```
```

--------------------------------

### Query PGS Catalog by Publication

Source: https://context7.com/pgscatalog/pygscatalog/llms.txt

Query the PGS Catalog API for all scoring files associated with a given publication accession.

```python
from pgscatalog.core.lib import CatalogQuery, CatalogCategory

# Query by publication
query = CatalogQuery(accession="PGP000001")
results = query.score_query()  # Returns all scores from publication
```

--------------------------------

### pgscatalog-ancestry-adjust

Source: https://context7.com/pgscatalog/pygscatalog/llms.txt

Adjusts PGS scores for genetic ancestry using provided reference and target population data.

```APIDOC
## pgscatalog-ancestry-adjust

### Description
Adjusts PGS scores for genetic ancestry.

### Method
CLI Command

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Command Example
```bash
pgscatalog-ancestry-adjust --agg_scores aggregated_scores.txt.gz \
    --psam reference.psam \
    --ref_pcs ref.pcs \
    --target_pcs target.pcs \
    --reference_related ref.king.cutoff.id \
    --dataset hgdp \
    --reference reference \
    --outdir ancestry_results
```

### Required Inputs
- `--agg_scores`: Aggregated scores in long format (from pgscatalog-aggregate)
- `--psam`: Reference population sample info with ancestry labels (SuperPop column)
- `--ref_pcs`: PCA from reference population (from fraposa-pgsc)
- `--target_pcs`: Target population PCA projected onto reference
- `--reference_related`: Relatedness cutoff file for reference population
```

--------------------------------

### Access and Write Ancestry Adjustment Results

Source: https://context7.com/pgscatalog/pygscatalog/llms.txt

Accesses the adjusted PGS values, models, and PCA data, and writes the results to a specified directory.

```python
print(results.pgs)  # Adjusted PGS values
print(results.models)  # Adjustment models
print(results.pca)  # PCA with ancestry assignments

# Write results to directory
results.write(directory="ancestry_output/")
# Creates: target_info.json.gz, target_pgs.txt.gz, target_popsimilarity.txt.gz
```

--------------------------------

### Validate a single scoring file

Source: https://github.com/pgscatalog/pygscatalog/blob/main/docs/how-to/guides/validate.rst

Validate a specific scoring file and output logs to a directory.

```bash
$ mkdir log
$ pgscatalog-validate -t formatted -f PGS000001.txt.gz --log_dir log/
```

--------------------------------

### Match Variants by Chromosome with pgscatalog-match

Source: https://github.com/pgscatalog/pygscatalog/blob/main/docs/how-to/guides/match.rst

Advanced usage for matching large datasets by processing each chromosome separately. Use the --chrom and --only_match flags. This generates intermediate match files in Arrow IPC format.

```bash
mkdir matchout
pgscatalog-match --dataset test --scorefiles normalised_scorefile.txt --target variants_chrom1.pvar --outdir matchout --chrom 1 --only_match
```

--------------------------------

### ScoringFileFrame: Normalized Scoring File

Source: https://context7.com/pgscatalog/pygscatalog/llms.txt

Represents a normalized scoring file backed by polars for efficient matching.

```APIDOC
## ScoringFileFrame

### Description
Represents a normalized scoring file backed by polars for efficient matching.

### Usage
```python
from pgscatalog.match.lib import ScoringFileFrame
scorefile = ScoringFileFrame("normalised_scorefile.txt", chrom="22")
with scorefile as score_df:
    print(score_df.collect().shape)
```
```

--------------------------------

### Match Variants with pgscatalog-match

Source: https://context7.com/pgscatalog/pygscatalog/llms.txt

Use pgscatalog-match to align genetic variants between scoring files and target genome information. It supports matching by chromosome for large datasets and can merge results from chromosome-split matches.

```bash
mkdir matchout
pgscatalog-match --dataset test \
    --scorefiles normalised_scorefile.txt \
    --target variants.pvar \
    --outdir matchout \
    --min_overlap 0.75
```

```bash
pgscatalog-match --dataset test \
    --scorefiles normalised_scorefile.txt \
    --target variants_chrom1.pvar \
    --outdir matchout \
    --chrom 1 \
    --only_match
```

```bash
pgscatalog-matchmerge --dataset test \
    --scorefiles normalised_scorefile.txt \
    --matches path/to/matchfile \
    --outdir matchmergeout \
    --min_overlap 0.75
```

--------------------------------

### Merge Chromosome Matches with pgscatalog-matchmerge

Source: https://github.com/pgscatalog/pygscatalog/blob/main/docs/how-to/guides/match.rst

Merge individual chromosome match files generated by pgscatalog-match. Specify the dataset, score files, path to match files, output directory, and minimum overlap.

```bash
pgscatalog-matchmerge --dataset test --scorefiles normalised_scorefile.txt --matches path/to/matchfile --outdir matchmergeout --min_overlap 0.75
```

--------------------------------

### Query PGS Catalog by PGS ID

Source: https://context7.com/pgscatalog/pygscatalog/llms.txt

Query the PGS Catalog API for a specific PGS ID. Retrieve score details and download URLs for original or harmonized files.

```python
from pgscatalog.core.lib import CatalogQuery, CatalogCategory

# Query by PGS ID
query = CatalogQuery(accession="PGS000001")
result = query.score_query()
print(result.pgs_id)  # 'PGS000001'
print(result.get_download_url())  # FTP URL for original file
print(result.get_download_url(GenomeBuild.GRCh38))  # URL for harmonised file
```

--------------------------------

### Aggregate Split PGS Files with pgscatalog-aggregate

Source: https://context7.com/pgscatalog/pygscatalog/llms.txt

Use pgscatalog-aggregate to combine PGS scores that have been split across multiple files, such as by chromosome or effect type. It supports compressed input files (gzip and zstandard).

```bash
pgscatalog-aggregate -s hgdp_14_additive_0.sscore.zst \
    hgdp_17_additive_0.sscore.zst \
    hgdp_22_additive_0.sscore.zst \
    -o aggregated \
    --verbose
```

--------------------------------

### Validate Scoring File Format

Source: https://context7.com/pgscatalog/pygscatalog/llms.txt

Validate a single formatted or harmonized scoring file, or all files in a directory, against PGS Catalog standards. Requires a log directory.

```bash
mkdir log
pgscatalog-validate -t formatted -f PGS000001.txt.gz --log_dir log/
```

```bash
pgscatalog-validate -t harmonized -f PGS000001_hmPOS_GRCh38.txt.gz --log_dir log/
```

```bash
pgscatalog-validate -t formatted --dir scores_directory/ --log_dir log/
```

--------------------------------

### Intersect Variants with pgscatalog-intersect

Source: https://context7.com/pgscatalog/pygscatalog/llms.txt

This command intersects variants between reference panels and target genomes, useful for PCA analysis. It allows filtering by minor allele frequency and genotype missingness.

```bash
pgscatalog-intersect --ref GRCh38_1000G_ALL.pvar.zst \
    --target GRCh38_hgdp_5.pvar.zst \
    --chrom 5 \
    --maf_target 0.1 \
    --geno_miss 0.1 \
    --outdir . \
    -v
```

--------------------------------

### Concatenate ScoringFiles Objects

Source: https://context7.com/pgscatalog/pygscatalog/llms.txt

Combine multiple ScoringFiles objects into a single object using the '+' operator.

```python
from pgscatalog.core.lib import ScoringFiles, GenomeBuild

# Concatenate ScoringFiles
combined = ScoringFiles('PGS000001') + ScoringFiles('PGS000002', 'PGS000003')
```

--------------------------------

### Calculate and Aggregate Polygenic Scores

Source: https://context7.com/pgscatalog/pygscatalog/llms.txt

Load, aggregate, and export polygenic scores from plink2 output.

```python
from pgscatalog.calc.lib import PolygenicScore

# Load a single score file
pgs1 = PolygenicScore(sampleset="test", path="chr22_additive.sscore.zst")

# Read score data
df = pgs1.read()
print(df)  # pandas DataFrame with DENOM, SUM columns per sample

# Aggregate scores (element-wise addition)
pgs2 = PolygenicScore(sampleset="test", path="chr21_additive.sscore.zst")
aggregated = pgs1 + pgs2

# Recalculate average after aggregation
aggregated.average()
print(aggregated.df)  # Now includes AVG column

# Write aggregated scores
import tempfile
outdir = tempfile.mkdtemp()
aggregated.write(outdir)  # Creates aggregated_scores.txt.gz

# Write split by sampleset
aggregated.write(outdir, split=True)  # Creates {sampleset}_pgs.txt.gz
```

--------------------------------

### Intersect Variants: HGDP vs 1000 Genomes

Source: https://github.com/pgscatalog/pygscatalog/blob/main/docs/how-to/guides/intersect.rst

Use pgscatalog-intersect to match variants between HGDP and 1000 Genomes reference panels. Specify chromosome, target MAF, genotype missingness, and output directory. The -v flag enables verbose output.

```bash
pgscatalog-intersect --ref GRCh38_1000G_ALL.pvar.zst \
    --target GRCh38_hgdp_5.pvar.zst \
    --chrom 5 \
    --maf_target 0.1 \
    --geno_miss 0.1 \
    --outdir .
    -v
```

--------------------------------

### PolygenicScore: Work with Calculated Scores

Source: https://context7.com/pgscatalog/pygscatalog/llms.txt

Represents plink2 --score output with methods for aggregation and writing.

```APIDOC
## PolygenicScore

### Description
Represents plink2 --score output with methods for aggregation and writing.

### Usage
```python
from pgscatalog.calc.lib import PolygenicScore
pgs1 = PolygenicScore(sampleset="test", path="chr22_additive.sscore.zst")
aggregated = pgs1 + pgs2
aggregated.average()
aggregated.write("output_dir")
```
```

--------------------------------

### Iterate Over Variants in Scoring File

Source: https://context7.com/pgscatalog/pygscatalog/llms.txt

Iterate through the variants within a ScoringFile object to access details like rsID, chromosome, position, effect allele, and weight.

```python
from pgscatalog.core.lib import ScoringFile, GenomeBuild

# Iterate over variants
for variant in sf.variants:
    print(f"{variant.rsID}: {variant.chr_name}:{variant.chr_position}")
    print(f"Effect allele: {variant.effect_allele}, Weight: {variant.effect_weight}")
    break
```

--------------------------------

### VariantFrame: Target Genome Variants

Source: https://context7.com/pgscatalog/pygscatalog/llms.txt

Represents variants from a target genome file (plink pvar/bim format) backed by polars.

```APIDOC
## VariantFrame

### Description
Represents variants from a target genome file (plink pvar/bim format) backed by polars.

### Usage
```python
from pgscatalog.match.lib import VariantFrame
target = VariantFrame("variants.pvar", dataset="my_dataset")
with target as target_df:
    print(target_df.collect().shape)
```
```

--------------------------------

### Adjust Polygenic Scores for Ancestry

Source: https://context7.com/pgscatalog/pygscatalog/llms.txt

Adjust aggregated polygenic scores using reference and target principal components.

```python
from pgscatalog.calc.lib import AggregatedPGS, PrincipalComponents, PopulationType, AdjustArguments

# Load aggregated scores
agg_pgs = AggregatedPGS(path="aggregated_scores.txt.gz", target_name="hgdp")

# Set up reference PCA
ref_pc = PrincipalComponents(
    pcs_path=["ref.pcs"],
    dataset="reference",
    psam_path="ref.psam",
    pop_type=PopulationType.REFERENCE,
    related_path="ref.king.cutoff.id"
)

# Set up target PCA
target_pc = PrincipalComponents(
    pcs_path="target.pcs",
    dataset="target",
    pop_type=PopulationType.TARGET
)

# Adjust for genetic ancestry
results = agg_pgs.adjust(ref_pc=ref_pc, target_pc=target_pc)
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.