ExperimentalImport: IReceptor import fails with "No objects to concatenate" on unmodified iReceptor data

[Reihaneh-Zarrin]

Sure! Here's the GitHub-flavored Markdown version, ready to paste into a GitHub issue:

---

Hi LIgO team,

I'm encountering an error when trying to import data using the IReceptor format in LIgO, as I was testing the ExperimentalImport data generator model.

The dataset was downloaded directly from the iReceptor Gateway and was not modified. It includes a ZIP file containing AIRR-compliant TSV files and a metadata.tsv.

My goal was to use ExperimentalImport in its simplest form, just to make sure it works as expected, but I keep getting an error during parsing.

---

YAML (dataset + simulation snippet)

definitions:
  datasets:
    experimental_dataset:
      format: IReceptor
      params:
        path: data.zip
        is_repertoire: true
        import_productive: true
        import_with_stop_codon: false
        import_out_of_frame: false
        import_illegal_characters: false
        import_empty_nt_sequences: true
        import_empty_aa_sequences: false
        region_type: FULL_SEQUENCE
        separator: "\t"
        column_mapping:
          junction: sequences
          junction_aa: sequence_aas
          v_call: v_alleles
          j_call: j_alleles
          locus: chains
          duplicate_count: counts
          sequence_id: sequence_identifiers

  simulations:
    sim1:
      is_repertoire: true
      paired: false
      sequence_type: amino_acid
      simulation_strategy: Implanting
      remove_seqs_with_signals: false
      sim_items:
        experimental_dataset:
          generative_model:
            type: ExperimentalImport
            import_format: IReceptor
            import_params: {}
            tmp_import_path: tmp_ligo_import
          immune_events:
            dummy_event: true
          number_of_examples: 100
          is_noise: false
          receptors_in_repertoire_count: 50
          signals: {}

instructions:
  inst1:
    type: LigoSim
    simulation: sim1
    export_p_gens: false
    max_iterations: 1
    number_of_processes: 1
    sequence_batch_size: 100

output:
  format: HTML

---

Data

• The file at data.zip was not modified after downloading from iReceptor.
• It contains multiple rearrangement .tsv files and a valid metadata.tsv file.
• I also tried extracting the ZIP file and pointing directly to a .tsv file inside it, but the same error occurred.
• The column mapping in the YAML matches the field names in the dataset.

---

Error

When I run LIgO with this YAML file, I get the following error. The traceback shows it fails during parsing at the point where airr.load_rearrangement() is called:

...
File ".../airr/interface.py", line 103, in load_rearrangement
  df = pd.read_csv(filename, sep='\t', header=0, index_col=None,
                   dtype=schema.pandas_types(), true_values=schema.true_values,
                   false_values=schema.false_values)
...
ValueError: No objects to concatenate
...
ImmuneMLParser: an error occurred during parsing in function parse_dataset

---

What I’ve verified

• The data structure follows the AIRR standard.
• The ZIP includes rearrangement .tsv files and a proper metadata.tsv.
• The YAML mappings are correct and complete.
• The dataset was downloaded as-is, no post-processing.
• I tried tweaking parameters like region_type, but it made no difference.
• I simply want to run a minimal simulation that produces HTML output based on real-world data.

---

Question

Is this a known issue when importing iReceptor data with ExperimentalImport?
Could it be due to how LIgO handles repertoire datasets in ZIP format or a mismatch in expected schema?

Any guidance would be appreciated!

Thanks in advance for your support

[pavlovicmilena]

Hi! I have now updated ligo to 1.0.10 on PyPI (and on the main branch here), and this error should not appear anymore. If it persists, please reopen the issue and provide the airr and pandas package versions where the import fails. Thank you for using ligo!

[Yasamin-Alemzadeh]

ExperimentalImport fails with IReceptor format: list indices must be integers or slices, not str

Description

I'm encountering an error when using ExperimentalImport with a dataset in IReceptor format. The import fails with a TypeError: list indices must be integers or slices, not str, even though the format and parameters seem correct.

I have updated Ligo to the latest version before running this.
Also, I am continuing this issue based on a message from my colleague who also encountered similar problems.

---

Environment

• ligo version: latest (installed via pip)
• pandas version: 2.2.3
• airr version: 1.5.1
• OS: Windows 11
• Python: 3.11

---

Error Traceback

File "IReceptorImport.py", line 238, in _get_static_metadata_df
    for repertoire in metadata_dict["Repertoire"]
TypeError: list indices must be integers or slices, not str

An error occurred while parsing the dataset experimental_dataset.
Exception: list indices must be integers or slices, not str

---

Spec File (YAML)

Here is a minimal version of my Ligo specification file:

definitions:
  datasets:
    experimental_dataset:
      format: IReceptor
      params:
        path: Dataset/
        is_repertoire: true
        import_productive: true
        import_with_stop_codon: false
        import_out_of_frame: false
        import_illegal_characters: false
        import_empty_nt_sequences: true
        import_empty_aa_sequences: false
        region_type: FULL_SEQUENCE
        separator: "\t"
        column_mapping:
          junction: junction
          junction_aa: junction_aa
          v_call: v_call
          j_call: j_call
          locus: locus
          duplicate_count: duplicate_count
          sequence_id: sequence_id


  simulations:
    sim1:
      is_repertoire: true
      paired: false
      sequence_type: amino_acid
      simulation_strategy: Implanting
      remove_seqs_with_signals: false
      sim_items:
        experimental_dataset:
          generative_model:
            type: ExperimentalImport
            import_format: IReceptor
            import_params: {}
            tmp_import_path: tmp_ligo_import
          immune_events:
            dummy_event: true
          number_of_examples: 100
          is_noise: false
          receptors_in_repertoire_count: 50
          signals: {}

instructions:
  inst1:
    type: LigoSim
    simulation: sim1
    export_p_gens: false
    max_iterations: 1
    number_of_processes: 1
    sequence_batch_size: 100

output:
  format: HTML

---

Observed Behavior

The error occurs during _get_static_metadata_df, which assumes metadata_dict["Repertoire"] is a dictionary. However, based on the error, it seems that metadata_dict is a list, not a dictionary.

---

Expected Behavior

I expected the dataset in IReceptor format to be parsed successfully and used in simulation with ExperimentalImport.

---

Possible Cause

The bug might be caused by assuming the AIRR metadata file is a dictionary when it's already a list of repertoires. This may be an incompatibility with newer AIRR formats or an improper fallback when the metadata is missing/empty.

---

Request

Could you please check whether:

• The ExperimentalImport class handles IReceptor metadata properly?
• A fix could be introduced to handle AIRR metadata represented as a list?

Let me know if a minimal dataset is needed; I’d be happy to provide a sample.

Thanks a lot for your great work on Ligo!

[pavlovicmilena]

Hi! I cannot replicate this with the data I just downloaded from iReceptor - could you provide a small dataset where I could replicate this bug? Thanks!

[Yasamin-Alemzadeh]

Hi,

Could you please provide a working example of a YAML specification that uses ExperimentalImport with the IReceptor format?

Specifically, we’d like it to:

• Import full sequences using region_type: FULL_SEQUENCE
• Work with data downloaded from iReceptor (AIRR .tsv + metadata .json)
• Produce synthetic output (e.g., HTML or TSV)

I wasn’t able to attach dataset file,We’d appreciate a YAML example that is compatible with it.
Additionally, to clarify our current objective:

Our task is to write a YAML specification that:

• 1. Uses ExperimentalImport
• 2. Specifies the input format as IReceptor
• 3. Both imports and outputs the full immune receptor sequence (i.e., region_type: FULL_SEQUENCE)

Despite multiple attempts, we continue to encounter errors and have been unable to get a working configuration.

Would it be possible for you to assist us with this? A minimal, working YAML example would be greatly appreciated.

Thank you in advance!

[Yasamin-Alemzadeh]

ir_2025-05-25_1550_68333c4716a07.zip

❗ ExperimentalImport Fails with IReceptor Format

📋 Description

When using ExperimentalImport with the IReceptor format, I encountered the following error during import:

Error when encoding TGTGCGAGACAGAAGGACTACTACAGGGACGTCTGGTGTGCGAGACACATATCTGTGGTGCGGCCATCGTCCATGACCGCTTTTGACTACTGGTGTGCGA to AlphabetEncoding. Invalid character(s): ['.', '.', '.'][46, 46, 46]

🗂️ Dataset

I’ve attached a sample dataset (sample_ireceptor_dataset.zip) containing:

• AIRR .tsv file
• Corresponding metadata .json

This dataset reproduces the error.

I hope the attached dataset helps to reproduce and resolve the issue.
Kind regards,

[pavlovicmilena]

Hi,

I have now updated the ligo version to reflect the changes, and the import worked out. I used the iReceptor file you attached here. Here is an example of the specification.

Please note that max_iterations x sequence_batch_size must be large enough to simulate number_of_examples x receptors_in_repertoire_count across all simulation items.

definitions:
  simulations:
    sim1:
      is_repertoire: true
      paired: false
      sequence_type: amino_acid
      simulation_strategy: Implanting
      remove_seqs_with_signals: false
      sim_items:
        experimental_dataset:
          generative_model:
            type: ExperimentalImport
            import_format: IReceptor
            import_params:
              path: ir_2025-05-25_1550_68333c4716a07.zip # the zip file you provided
            tmp_import_path: tmp_ligo_import
          immune_events:
            dummy_event: true
          number_of_examples: 100
          is_noise: false
          receptors_in_repertoire_count: 50
          signals: {}

instructions:
  inst1:
    type: LigoSim
    simulation: sim1
    export_p_gens: false
    max_iterations: 10
    number_of_processes: 1
    sequence_batch_size: 1000

[Reihaneh-Zarrin]

Thank you so much for sending the YAML file. We really appreciate it.

After reviewing both the documentation and your file, I feel that writing a correct YAML specification just by following the documentation alone wouldn’t really have been possible. The documentation is detailed but somewhat complex, and the exact order and structure of parameters aren’t always clear.

To keep it short, I just wanted to let you know that we were finally able to get an output for the first time by running the YAML file you provided — but we’re still struggling to make it import the full sequence, which was actually the main reason we switched from OLGA to ExperimentalImport.

Ultimately, we want to add specific motifs and signals to the data to simulate diseases like cancer.
But for now, I wanted to share two main issues we’re encountering:

1. When I set the region_type to FULL_SEQUENCE, I either get an error saying it’s not a valid region type, or the setting is simply ignored.
2. When I change the sequence_type to nucleotide, I also encounter an error.

Lastly, I noticed it doesn’t seem to work with AIRR 1.5.1 — I had to downgrade to 1.4.1 to get any output.

Here’s the YAML file we are currently using and getting errors with:

definitions:
  simulations:
    sim1:
      is_repertoire: true
      paired: false
      sequence_type: nucleotide  
      simulation_strategy: Implanting
      remove_seqs_with_signals: false
      sim_items:
        experimental_dataset:
          generative_model:
            type: ExperimentalImport
            import_format: IReceptor
            import_params:
              path: ir_2025-05-25_1550_68333c4716a07.zip 
              region_type: FULL_SEQUENCE 
            tmp_import_path: tmp_ligo_import
          immune_events:
            dummy_event: true
          number_of_examples: 100
          is_noise: false
          receptors_in_repertoire_count: 50
          signals: {}

instructions:
  inst1:
    type: LigoSim
    simulation: sim1
    export_p_gens: false
    max_iterations: 10
    number_of_processes: 1
    sequence_batch_size: 1000

The simulation currently fails with this error:

RuntimeError: Unsupported region type for IMGT numbering encountered during simulation: RegionType.FULL_SEQUENCE.

It seems that the FULL_SEQUENCE region type is not yet supported in LIgO for IMGT numbering, so this is causing the failure. Based on the documentation, it looks like it should be a valid region type, but it doesn’t seem to work in practice.

I wanted to kindly ask if you could check whether the model can solve both of these issues, and also whether it can later handle the addition of motifs and signals.

Thanks again so much for your support — we really appreciate the time and help you’ve provided!