{"id":10196,"library":"refgenie","title":"Refgenie","description":"Refgenie creates a standardized folder structure for reference genome files and indexes, facilitating their sharing and usage across different bioinformatics tools and analyses. The current version is 0.13.0, with new releases typically occurring a few times per year, focusing on bug fixes, feature enhancements, and occasional schema updates.","status":"active","version":"0.13.0","language":"en","source_language":"en","source_url":"https://github.com/databio/refgenie","tags":["genomics","bioinformatics","reference genomes","data management","cli"],"install":[{"cmd":"pip install refgenie","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Core dependency for genome data management.","package":"genomelake","optional":false},{"reason":"Configuration and YAML management utility.","package":"yacman","optional":false},{"reason":"Optional dependency for enhanced CLI output.","package":"rich","optional":true},{"reason":"Optional dependency for containerized build and management features.","package":"docker","optional":true}],"imports":[{"symbol":"RefgenieClient","correct":"from refgenie import RefgenieClient"},{"symbol":"RefgenieProject","correct":"from refgenie import RefgenieProject"},{"note":"The CLI module was moved to `refgenie.cli` in version 0.11.0. Direct import of `cli` from `refgenie` is no longer supported for accessing CLI functions, though most users interact via the `refgenie` command directly.","wrong":"from refgenie import cli","symbol":"cli","correct":"import refgenie.cli"}],"quickstart":{"code":"import refgenie\nimport os\n\n# Initialize RefgenieClient. It will look for ~/.refgenie/refgenie.yaml by default.\n# For a temporary or custom config, provide the path.\n# If no config is found at the default path, an empty client is initialized.\n# For this example, we'll try to use a default or an empty one.\n\n# Create a dummy refgenie.yaml for demonstration if it doesn't exist\nconfig_path = os.path.expanduser(\"~/.refgenie/refgenie.yaml\")\nif not os.path.exists(os.path.dirname(config_path)):\n    os.makedirs(os.path.dirname(config_path))\nif not os.path.exists(config_path):\n    with open(config_path, 'w') as f:\n        f.write(\"refgenie:\\n  genome_config_version: 0.2\\n  genomes: {}\\n\")\n\nrg = refgenie.RefgenieClient(config_file=config_path)\n\nprint(f\"Refgenie client initialized. Config file: {rg.config_file}\")\n\n# List available genomes (will be empty if no assets are pulled)\ngenomes = rg.list_genomes()\nprint(f\"Available genomes: {list(genomes.keys())}\")\n\n# Example: trying to get an asset (will likely fail if not pulled/built)\n# To make this runnable without pre-pulled assets, we'll skip direct asset retrieval\n# Try to get a non-existent asset to show expected behavior without erroring\ntry:\n    # This assumes 'human_genome' is a valid genome and 'fasta' is an asset for it\n    # For a real scenario, you would run `refgenie pull human_genome/fasta` first\n    # or build your own assets.\n    # asset_path = rg.get_asset(\"human_genome/fasta\")\n    # print(f\"Path to human_genome fasta: {asset_path}\")\n    print(\"To get an asset, first ensure it's pulled or built locally.\")\n    print(\"Example: 'refgenie pull hg38/fasta' from command line.\")\nexcept Exception as e:\n    print(f\"Could not retrieve asset (expected if not pulled): {e}\")\n\n# Clean up dummy config for demonstration\n# os.remove(config_path)\n# os.rmdir(os.path.dirname(config_path)) # Only if directory is empty\n","lang":"python","description":"Initialize a RefgenieClient, list available genomes, and demonstrate how to interact with assets. This example includes a setup for a dummy config file to make it runnable even if Refgenie hasn't been initialized via the CLI, though actual asset retrieval requires prior `refgenie pull` or `refgenie build` commands."},"warnings":[{"fix":"Run `refgenie config upgrade` from the command line after updating the `refgenie` library to ensure your configuration file is compatible with the installed version.","message":"Refgenie config file schema has undergone breaking changes across major versions (e.g., 0.10.0). Using an older `refgenie.yaml` with a newer version of the library can lead to errors.","severity":"breaking","affected_versions":"prior to 0.10.0, and other minor upgrades"},{"fix":"Replace all instances of `refgenie add` with `refgenie build` in scripts and commands.","message":"The primary CLI command for adding new assets changed from `refgenie add` to `refgenie build` in version 0.9.0. Using the old command with newer versions will result in a 'command not found' error.","severity":"breaking","affected_versions":"0.9.0 and later"},{"fix":"Always explicitly check `rg.list_genomes()` or `rg.config_file` after initialization to confirm the client has loaded the expected configuration. For custom paths, provide `config_file='/path/to/my/refgenie.yaml'`.","message":"The `RefgenieClient` constructor will by default attempt to load `~/.refgenie/refgenie.yaml`. If this file doesn't exist, it will initialize an empty client without raising an error. This can lead to unexpected behavior if you expect an error for a missing configuration or an automatically populated client.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Open your terminal and execute `refgenie config upgrade`.","cause":"Your `refgenie.yaml` file's schema version is older than what the installed `refgenie` library expects.","error":"Error: Config file is outdated or invalid. Please run 'refgenie config upgrade'"},{"fix":"First, ensure your Refgenie client points to the correct config file and data directory. Then, pull or build the missing asset using the CLI, for example: `refgenie pull hg38/fasta` or `refgenie build hg38/fasta`.","cause":"The requested genome asset (e.g., `hg38/fasta`) has not been downloaded or built locally by Refgenie, or the client is not configured to point to the correct data directory.","error":"FileNotFoundError: [Errno 2] No such file or directory: '/path/to/refgenie/data/asset_name'"},{"fix":"Replace `refgenie add` with `refgenie build` in your command-line invocations.","cause":"You are attempting to use the deprecated `refgenie add` command with a Refgenie version (0.9.0+) that has replaced it with `refgenie build`.","error":"Error: No such command 'add'. Did you mean 'build'?"}]}